leadforge 1.0.0

Opinionated framework for generating synthetic CRM and GTM datasets from simulated commercial worlds

leadforge

Opinionated framework for generating synthetic CRM and GTM datasets from simulated commercial worlds.

Created by Shay Palachy Affek.

leadforge generates narrative-grounded synthetic revenue datasets — starting with lead scoring — designed for teaching, portfolio projects, and research. Rather than sampling rows from a distribution, it simulates a commercial world: a specific company, selling a specific product, to a specific kind of buyer, and renders realistic CRM-style outputs from that world.

Docs: leadforge-dev.github.io/leadforge · Dataset: HuggingFace · Kaggle: Intro · Intermediate · Advanced

---

What Makes LeadForge Different

• World-first generation: datasets are rendered from simulated companies, products, buyers, activities, opportunities, and outcomes.
• Relational CRM shape: output includes normalized tables plus task-ready train/validation/test splits for lead scoring.
• Pedagogical realism: snapshot discipline, redaction modes, leakage traps, calibration issues, and difficulty tiers are deliberate teaching material.

---

Installation

Requires Python 3.11+.

pip install leadforge

Or install directly from GitHub:

pip install git+https://github.com/leadforge-dev/leadforge.git

For development:

git clone https://github.com/leadforge-dev/leadforge.git
cd leadforge
pip install -e ".[dev]"
pre-commit install

---

Quickstart

CLI

# List available recipes
leadforge list-recipes

# Generate a dataset bundle
leadforge generate \
  --recipe b2b_saas_procurement_v1 \
  --seed 42 \
  --mode student_public \
  --difficulty intermediate \
  --n-leads 5000 \
  --out ./out/demo_bundle

# Inspect bundle metadata
leadforge inspect ./out/demo_bundle

# Or pipe the manifest into jq
leadforge inspect ./out/demo_bundle --json | jq .snapshot_day

# Validate bundle integrity
leadforge validate ./out/demo_bundle

Python API

from leadforge.api import Generator

gen = Generator.from_recipe(
    "b2b_saas_procurement_v1",
    seed=42,
    exposure_mode="student_public",
)
bundle = gen.generate(n_leads=5000, difficulty="intermediate")
bundle.save("./out/demo_bundle")

---

Generated Data Preview

A generated bundle looks like CRM and GTM data, not a generic tabular benchmark. This compact slice comes from the intermediate lead-scoring bundle:

split	industry	region	employee_band	lead_source	touch_count	session_count	opportunity_created	expected_acv	converted_within_90_days
train	logistics	UK	200-499	inbound_marketing	0	0	False	66,699	False
train	logistics	UK	500-999	inbound_marketing	5	2	False	58,372	False
train	logistics	US	200-499	partner_referral	9	3	True	15,462	False
train	healthcare_non_clinical	US	200-499	inbound_marketing	5	1	True	30,490	False
train	manufacturing	US	1000-1999	sdr_outbound	missing	1	True	42,999	False

The full bundle also includes accounts, contacts, leads, touches, sessions, sales activities, opportunities, feature dictionaries, manifests, and model-ready Parquet task splits.

---

Exposure Modes

Control what truth is visible in the output bundle:

Mode	Purpose	Includes
student_public	Teaching / portfolio use	Tables, features, task splits, dataset card
research_instructor	Full truth for instructors / researchers	All of the above + hidden graph, world spec, latent registry, mechanism summary

Set via --mode on the CLI or exposure_mode= in the Python API.

---

Difficulty Profiles

Each recipe ships with difficulty profiles that control signal-to-noise ratio:

Profile	Description
intro	Strong signal, low noise — good for first-time learners
intermediate	Moderate signal, realistic noise
advanced	Weak signal, high noise — challenges experienced practitioners

Set via --difficulty on the CLI or difficulty= in generate().

---

Output Bundle

bundle_root/
  manifest.json            # provenance, row counts, file hashes
  dataset_card.md          # human-readable dataset documentation
  feature_dictionary.csv   # feature names, types, descriptions
  tables/                  # 9 relational Parquet tables
  tasks/
    converted_within_90_days/
      train.parquet
      valid.parquet
      test.parquet
      task_manifest.json
  metadata/                # (research_instructor only) hidden graph, world spec, latents

---

Key Design Principles

• Deterministic: same (recipe, seed, version) → identical output.
• Relational-first: 9 normalized tables; flat ML exports are derived.
• No external APIs: core generation never requires network access.
• Simulation-driven labels: converted_within_90_days emerges from simulated events, not sampled directly.
• Leakage-safe: no feature uses events after the snapshot anchor.

---

Documentation

• Documentation site
• Quickstart
• Output bundle reference
• Generation method
• Break-me guide
• Changelog

---

Development

pip install -e ".[dev]"
pytest                        # run all tests (~800)
ruff check .                  # lint
ruff format .                 # format
mypy leadforge/               # type check
pre-commit run --all-files    # full pre-commit suite

---

License

MIT. See LICENSE.

---

Credits

Created by Shay Palachy Affek [GitHub]