From 5e6dfd8fa0d4bcd15446536b057f04114a3d68d5 Mon Sep 17 00:00:00 2001 From: Shay Palachy Date: Sat, 2 May 2026 11:31:15 +0300 Subject: [PATCH 1/2] docs: polish README and add CHANGELOG for v1.0 release Remove all stale "coming in vX.Y.Z" placeholders from README. Add working CLI quickstart, Python API example, exposure modes and difficulty profiles documentation, output bundle layout, and key design principles. Create CHANGELOG.md covering v0.1.0 through current state. Co-Authored-By: Claude Opus 4.6 --- .agent-plan.md | 8 ++++- CHANGELOG.md | 53 ++++++++++++++++++++++++++++ README.md | 96 ++++++++++++++++++++++++++++++++++++++++++-------- 3 files changed, 142 insertions(+), 15 deletions(-) create mode 100644 CHANGELOG.md diff --git a/.agent-plan.md b/.agent-plan.md index 235747f..9930697 100644 --- a/.agent-plan.md +++ b/.agent-plan.md @@ -148,6 +148,12 @@ Documentation + CI: - [x] `leadforge/render/snapshots.py` — added comment documenting the feature-label temporal mismatch when `label_window_days < horizon_days` (features aggregate over full horizon; label uses shorter window) - [x] 7 new tests: default-90 unchanged, shorter window fewer conversions, 1-day window zero conversions, late conversions excluded (with day-offset verification), conversion_timestamp still set outside window, event counts unchanged by window, bundle round-trip integration; total 788 passing +### M15: README + CHANGELOG polish (PR #46) + +- [x] `README.md` — removed all "coming in vX.Y.Z" placeholders; added working CLI quickstart, Python API example, exposure modes table, difficulty profiles table, output bundle layout, key design principles +- [x] `CHANGELOG.md` — created; covers v0.1.0 through post-v0.5.0 improvements; user-facing descriptions grouped by version +- [x] `.agent-plan.md` — updated deferred items table + ### Fix: direct conversion bypass for pre-SQL leads (PR #45, closes #44) - [x] `leadforge/simulation/engine.py` — added `_DIRECT_CONVERSION_STAGES` and `_DIRECT_CONVERSION_DISCOUNT` (0.01) constants; pre-SQL leads (`mql`, `sal`) now have a small daily probability of converting directly, bypassing the full funnel @@ -207,7 +213,7 @@ Documentation + CI: | M14: Notebook 2 (lead scoring baseline) | Deferred | v4 validation script covers this | | M14: Notebook 3 (public vs instructor) | Discarded | No current audience | | M14: Notebook 4 (recipe customization) | Discarded | Premature | -| M15: Docs polish + v1.0 RC | Deferred | Do after v4 ships | +| M15: Docs polish + v1.0 RC | **In progress** | README + CHANGELOG done; architecture diagram and notebooks remain | ### From post-v1 list diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..3a959d2 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,53 @@ +# Changelog + +All notable changes to leadforge are documented here. + +--- + +## v0.5.0 — Validation Harness & CLI Complete + +- Full validation harness: determinism checks, exposure monotonicity, realism bounds, difficulty validation, cross-seed drift detection. +- `leadforge validate` command with artifact checks, FK integrity, leakage detection, and task split validation. +- Parquet metadata used for row counts (no full table reads during validation). + +## v0.4.0 — Simulation Engine & End-to-End Generation + +- 90-day daily-step simulation engine with churn, stage advancement, conversion hazards, and touch emission. +- Population generation: accounts (3 latent traits), contacts (4 traits), leads (1 trait) with motif-family biases. +- Full render pipeline: 9-table relational output, leakage-free lead snapshots, deterministic train/valid/test splits. +- Exposure filtering: `student_public` and `research_instructor` modes with truth redaction. +- CLI commands: `generate`, `inspect`, `validate`, `list-recipes` — all fully wired. +- Bundle manifest with provenance, row counts, and SHA-256 file hashes. + +## v0.3.0 — World Structure & Mechanisms + +- Hidden world graph (DAG) with 5 motif families: fit-dominant, intent-dominant, sales-execution-sensitive, demo/trial-mediated, buying-committee-friction. +- Stochastic graph rewiring: optional-node dropping, edge-weight jitter, latent-confounder injection. +- Mechanism layer: latent scores, conversion hazards, stage transitions, Poisson intensities, categorical influences, noisy proxies. +- Motif-aware mechanism assignment policies. + +## v0.2.0 — Config, Recipes & Narrative + +- Typed `GenerationConfig`, `Recipe`, `WorldSpec` models with full precedence resolution (kwargs > override > recipe > defaults). +- Seeded RNG with SHA-256-derived named substreams for reproducibility. +- Narrative layer: company, product, market, GTM motion, personas, funnel stages — loaded from recipe YAML. +- Schema layer: 9 entity dataclasses, 10 FK constraints, 29 snapshot features, feature dictionary writer. +- Dataset card renderer from narrative + world spec. + +## v0.1.0 — Project Foundation + +- Package skeleton, CLI entry point (`leadforge list-recipes`), CI pipeline. +- Recipe registry with `b2b_saas_procurement_v1` recipe. +- GitHub Actions: lint, typecheck, test matrix (Python 3.11 + 3.12). + +--- + +## Post-v0.5.0 Improvements + +- **Direct conversion bypass** (PR #45): pre-SQL leads can now convert via a rare direct path, fixing the deterministic `is_sql → converts` invariant. +- **Configurable label window** (PR #43): `label_window_days` controls conversion label derivation in the simulation. +- **Generalized task support** (PR #40, #42): `primary_task` threaded through bundle, validation, and pipelines; dataset card prose adapts to non-conversion tasks. +- **Pipeline extraction** (PR #29, #34): build pipeline functions extracted into `leadforge.pipelines` with proper RNG conventions. +- **Latent-aware touch intensity** (PR #31): `LatentDecayIntensity` mechanism creates causal link between latent traits and touch patterns. +- **Canonical validation module** (PR #26): reusable lead scoring validation with sklearn pipeline. +- **v4–v6 dataset pipelines**: progressive dataset versions with leakage traps, student/instructor splits, value-aware scoring, and GBM improvement validation. diff --git a/README.md b/README.md index 8582db3..824541e 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ **Opinionated framework for generating synthetic CRM and GTM datasets from simulated commercial worlds.** -`leadforge` generates narrative-grounded synthetic revenue datasets starting with lead scoring, designed to support 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. +`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. --- @@ -25,27 +25,29 @@ pre-commit install ## Quickstart +### CLI + ```bash # List available recipes leadforge list-recipes -# Coming in v0.2.0: 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 +# 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 -# Coming in v0.4.0: inspect a generated bundle -# leadforge inspect ./out/demo_bundle +# Inspect bundle metadata +leadforge inspect ./out/demo_bundle -# Coming in v0.5.0: validate a generated bundle -# leadforge validate ./out/demo_bundle +# Validate bundle integrity +leadforge validate ./out/demo_bundle ``` -**Python API** (coming in v0.2.0): +### Python API ```python from leadforge.api import Generator @@ -61,11 +63,77 @@ bundle.save("./out/demo_bundle") --- +## 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/ # task splits (train/valid/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 - [Design document](docs/leadforge_design_doc.md) - [Architecture spec](docs/leadforge_architecture_spec.md) - [Implementation plan](docs/leadforge_implementation_plan.md) +- [v4 dataset design](docs/v4/design.md) +- [Changelog](CHANGELOG.md) + +--- + +## Development + +```bash +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 +``` --- From 4407a3e65f6b0d9ede14207bf7d154e3c5b82ebd Mon Sep 17 00:00:00 2001 From: Shay Palachy Date: Sat, 2 May 2026 11:49:23 +0300 Subject: [PATCH 2/2] fix: address review feedback on README and CHANGELOG - Add Python 3.11+ requirement to Installation - Replace `pip install leadforge` with git install (no PyPI yet) - Expand bundle tree to show task subdirectory nesting - CHANGELOG: rename versions to "Milestone 0.x.0", add dates - CHANGELOG: fold post-v0.5.0 items into "Unreleased" section Co-Authored-By: Claude Opus 4.6 --- CHANGELOG.md | 35 ++++++++++++++++++----------------- README.md | 13 +++++++++++-- 2 files changed, 29 insertions(+), 19 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3a959d2..ac9ae7c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,16 +1,29 @@ # Changelog All notable changes to leadforge are documented here. +Format inspired by [Keep a Changelog](https://keepachangelog.com/). --- -## v0.5.0 — Validation Harness & CLI Complete +## Unreleased + +- **Direct conversion bypass** (PR #45): pre-SQL leads can now convert via a rare direct path, fixing the deterministic `is_sql → converts` invariant. +- **Configurable label window** (PR #43): `label_window_days` controls conversion label derivation in the simulation. +- **Generalized task support** (PR #40, #42): `primary_task` threaded through bundle, validation, and pipelines; dataset card prose adapts to non-conversion tasks. +- **Pipeline extraction** (PR #29, #34): build pipeline functions extracted into `leadforge.pipelines` with proper RNG conventions. +- **Latent-aware touch intensity** (PR #31): `LatentDecayIntensity` mechanism creates causal link between latent traits and touch patterns. +- **Canonical validation module** (PR #26): reusable lead scoring validation with sklearn pipeline. +- **v4–v6 dataset pipelines**: progressive dataset versions with leakage traps, student/instructor splits, value-aware scoring, and GBM improvement validation. + +--- + +## Milestone 0.5.0 — Validation Harness & CLI Complete (2026-04-29) - Full validation harness: determinism checks, exposure monotonicity, realism bounds, difficulty validation, cross-seed drift detection. - `leadforge validate` command with artifact checks, FK integrity, leakage detection, and task split validation. - Parquet metadata used for row counts (no full table reads during validation). -## v0.4.0 — Simulation Engine & End-to-End Generation +## Milestone 0.4.0 — Simulation Engine & End-to-End Generation (2026-04-28) - 90-day daily-step simulation engine with churn, stage advancement, conversion hazards, and touch emission. - Population generation: accounts (3 latent traits), contacts (4 traits), leads (1 trait) with motif-family biases. @@ -19,14 +32,14 @@ All notable changes to leadforge are documented here. - CLI commands: `generate`, `inspect`, `validate`, `list-recipes` — all fully wired. - Bundle manifest with provenance, row counts, and SHA-256 file hashes. -## v0.3.0 — World Structure & Mechanisms +## Milestone 0.3.0 — World Structure & Mechanisms (2026-04-25) - Hidden world graph (DAG) with 5 motif families: fit-dominant, intent-dominant, sales-execution-sensitive, demo/trial-mediated, buying-committee-friction. - Stochastic graph rewiring: optional-node dropping, edge-weight jitter, latent-confounder injection. - Mechanism layer: latent scores, conversion hazards, stage transitions, Poisson intensities, categorical influences, noisy proxies. - Motif-aware mechanism assignment policies. -## v0.2.0 — Config, Recipes & Narrative +## Milestone 0.2.0 — Config, Recipes & Narrative (2026-04-20) - Typed `GenerationConfig`, `Recipe`, `WorldSpec` models with full precedence resolution (kwargs > override > recipe > defaults). - Seeded RNG with SHA-256-derived named substreams for reproducibility. @@ -34,20 +47,8 @@ All notable changes to leadforge are documented here. - Schema layer: 9 entity dataclasses, 10 FK constraints, 29 snapshot features, feature dictionary writer. - Dataset card renderer from narrative + world spec. -## v0.1.0 — Project Foundation +## Milestone 0.1.0 — Project Foundation (2026-04-18) - Package skeleton, CLI entry point (`leadforge list-recipes`), CI pipeline. - Recipe registry with `b2b_saas_procurement_v1` recipe. - GitHub Actions: lint, typecheck, test matrix (Python 3.11 + 3.12). - ---- - -## Post-v0.5.0 Improvements - -- **Direct conversion bypass** (PR #45): pre-SQL leads can now convert via a rare direct path, fixing the deterministic `is_sql → converts` invariant. -- **Configurable label window** (PR #43): `label_window_days` controls conversion label derivation in the simulation. -- **Generalized task support** (PR #40, #42): `primary_task` threaded through bundle, validation, and pipelines; dataset card prose adapts to non-conversion tasks. -- **Pipeline extraction** (PR #29, #34): build pipeline functions extracted into `leadforge.pipelines` with proper RNG conventions. -- **Latent-aware touch intensity** (PR #31): `LatentDecayIntensity` mechanism creates causal link between latent traits and touch patterns. -- **Canonical validation module** (PR #26): reusable lead scoring validation with sklearn pipeline. -- **v4–v6 dataset pipelines**: progressive dataset versions with leakage traps, student/instructor splits, value-aware scoring, and GBM improvement validation. diff --git a/README.md b/README.md index 824541e..5d7a2e9 100644 --- a/README.md +++ b/README.md @@ -8,10 +8,14 @@ ## Installation +Requires **Python 3.11+**. + ```bash -pip install leadforge +pip install git+https://github.com/leadforge-dev/leadforge.git ``` +> PyPI package coming with the v1.0 release. + For development: ```bash @@ -98,7 +102,12 @@ bundle_root/ dataset_card.md # human-readable dataset documentation feature_dictionary.csv # feature names, types, descriptions tables/ # 9 relational Parquet tables - tasks/ # task splits (train/valid/test Parquet + task_manifest.json) + tasks/ + converted_within_90_days/ + train.parquet + valid.parquet + test.parquet + task_manifest.json metadata/ # (research_instructor only) hidden graph, world spec, latents ```