fauxdata-cli 0.1.6__tar.gz → 0.2.0__tar.gz

{fauxdata_cli-0.1.6 → fauxdata_cli-0.2.0}/LOG.md

@@ -1,5 +1,26 @@
 # Log
 
+## 2026-10-11 — 0.2.0 (non rilasciata): pointblank 1.0.1, `precision` nativa, `col_vals_str_len`, fix, comando `agent` e `--json`
+
+- Bump `pointblank>=1.0.1` (da 0.25.0). 103/103 test invariati; schemi inclusi PASS; stesso seed → CSV identici byte per byte tra 0.25 e 1.0.1. Effetto collaterale: da 0.27 pointblank richiede `anthropic[bedrock]` → 20 pacchetti in più installati (anthropic, boto3, pydantic, …), non usati da fauxdata.
+- `precision` float: ora nativa (`pb.float_field(precision=)`), unicità garantita dopo l'arrotondamento. Limiti stretti verso l'interno sulla griglia dei decimali (`max: 9.999`, `precision: 2` → `9.99`) perché l'arrotondamento non sfori il range; errore chiaro se nessun valore ci sta. Documentata nel README (prima non lo era).
+- Nuova regola `col_vals_str_len` (`column`, `min`/`max`, null ignorati). `infer` la emette solo per stringhe libere: su preset/pattern/values il generatore ignora le lunghezze.
+- Fix: le regole sui valori (`between`, `gt/lt/ge/le`, `regex`, `in_set`) ignorano i null (`na_pass=True`; `in_set` via `None` nel set). Prima una colonna col 20% di null falliva 195/1000 righe.
+- Fix: `infer --categorical-threshold` da CLI arrivava come float (anche il default) e pointblank lo leggeva come frazione → ogni colonna stringa senza preset diventava categorica con i valori reali copiati in `values:`. Ora gli interi ≥ 1 passano come conteggio.
+- Fix: `values` sulle colonne `int`/`float` ora rispettato in generazione (passato come `allowed`); prima `infer` lo emetteva per gli int a bassa cardinalità e il generatore lo ignorava (403/500 fallimenti in round-trip).
+- Fix: `rows_distinct` esclude le righe con null nelle colonne controllate (come SQL UNIQUE); prima i null contavano come duplicati tra loro.
+- Bug di pointblank (non nostro): `unique=True` ignorato sui preset coerenti (`email`, `name`, `city`, …); segnalato in https://github.com/posit-dev/pointblank/issues/441. Non corretto: `unique` + `nullable` su range stretto non generabile.
+- Nuovo comando `fauxdata agent`: guida Markdown per agenti AI (flusso, output JSON, exit code, schema, tipi, preset, regole, esempio); liste generate dalle costanti di `schema.py`.
+- Nuovo flag `--json` su `generate`, `validate`, `infer`, `preview`: stdout contiene solo un oggetto JSON; errori come `{"error": ...}` con exit 1. Sezione README "Using fauxdata with AI agents".
+- Fix: un passo su una colonna assente dal dataset risultava `ok: true` con 0/0 righe; ora campo `evaluated` (da `validation_info`), `ok: false`, `NOT RUN` in tabella. `get_dataframe_report()` non usabile: fallisce con `rows_distinct`/`rows_complete` + `columns_subset` (segnalato in https://github.com/posit-dev/pointblank/issues/442). Chiude la issue #1 di fauxdata (output strutturato → `--json`).
+- Sito `docs/index.html`: badge pointblank 1.0+, "six commands", righe `infer` e `agent`, `--json`.
+- 143/143 test, coverage 87.05%.
+
+## 2026-07-04 — v0.1.6
+
+- Release `0.1.6`: include il fix issue #2 (`precision` float). Build con `uv build`, tag `v0.1.6`.
+- Deploy PyPI **manuale** (`uv publish`): nessun workflow di release automatico.
+
 ## 2026-07-04 — fix issue #2: `precision` float ignorato
 
 - Bug: l'opzione `precision` dei float veniva letta nello schema ma mai applicata (`pb.float_field` non ha il parametro). Valori generati con precisione piena.

{fauxdata_cli-0.1.6 → fauxdata_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: fauxdata-cli
-Version: 0.1.6
+Version: 0.2.0
 Summary: CLI for generating and validating fake datasets
 Project-URL: Homepage, https://aborruso.github.io/fauxdata/
 Project-URL: Repository, https://github.com/aborruso/fauxdata
@@ -13,7 +13,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.11
-Requires-Dist: pointblank>=0.25
+Requires-Dist: pointblank>=1.0.1
 Requires-Dist: polars>=1.0
 Requires-Dist: pyfiglet>=1.0
 Requires-Dist: pyyaml>=6.0
@@ -170,12 +170,26 @@ validation:
 | Type | Description | Options |
 |------|-------------|---------|
 | `int` | Integer | `min`, `max`, `unique` |
-| `float` | Floating point | `min`, `max` |
+| `float` | Floating point | `min`, `max`, `precision` |
 | `string` | Text | `preset`, `values`, `pattern`, `unique`, `min_length`, `max_length` |
 | `bool` | Boolean | — |
 | `date` | Date | `min`, `max` (ISO format) |
 | `datetime` | Datetime | `min`, `max` (ISO format) |
 
+### Float precision
+
+`precision` sets the number of decimal places of a `float` column, e.g. `precision: 2` for prices:
+
+```yaml
+price:
+  type: float
+  min: 1.0
+  max: 199.999
+  precision: 2
+```
+
+Rounding never pushes a value outside `min`/`max`. When a bound has more decimals than `precision`, fauxdata moves it inward to the nearest value that fits: in the example above `max: 199.999` becomes `199.99`, so no generated price can round up to `200.00`. If no value with the requested decimals fits between `min` and `max` (e.g. `min: 1.001`, `max: 1.009`, `precision: 2`), `generate` stops with an error instead of producing out-of-range data. With `unique: true`, values are unique after rounding.
+
 ### String presets
 
 Presets generate realistic, locale-aware values. Set `locale` at the schema level to control the country.
@@ -230,6 +244,7 @@ Supported locales include: `US`, `IT`, `DE`, `FR`, `ES`, `JP`, `BR`, `PL`, `NL`,
 | `col_vals_between` | Value in range | `column`, `min`, `max` |
 | `col_vals_regex` | Matches pattern | `column`, `pattern` |
 | `col_vals_in_set` | Value in allowed set | `column`, `values` |
+| `col_vals_str_len` | String length in range (nulls are ignored) | `column`, `min` and/or `max` |
 | `col_vals_gt` / `col_vals_lt` | Greater / less than | `column`, `min` / `max` |
 | `col_vals_ge` / `col_vals_le` | Greater / less or equal | `column`, `min` / `max` |
 | `rows_distinct` | Unique rows | `columns` |
@@ -256,6 +271,7 @@ fauxdata generate schemas/people.yml --out - --format jsonl | wc -l
 | `--format` | `-f` | from schema | Output format: `csv`, `parquet`, `json`, `jsonl`, `jsonlines` |
 | `--seed` | `-s` | from schema | Random seed for reproducibility |
 | `--validate` | `-v` | off | Run validation rules after generating |
+| `--json` | | off | Print only a JSON summary to stdout (see [Using fauxdata with AI agents](#using-fauxdata-with-ai-agents)) |
 
 When `--out -` is used, all output messages are suppressed and only data is written to stdout.
 
@@ -317,6 +333,36 @@ Interactive wizard to create a new schema template. Asks for name, description,
 
 ---
 
+## Using fauxdata with AI agents
+
+fauxdata is designed to be driven by AI agents as well as by people.
+
+**Start with `fauxdata agent`.** It prints a Markdown guide with everything an agent needs to use the tool without reading this README: the workflow, the schema format, column types and options, presets, validation rules, the JSON output of each command, exit codes and a complete example schema. The lists of types, presets and rules are built from the code, so the guide always matches the installed version.
+
+```
+fauxdata agent > fauxdata-guide.md
+```
+
+**Add `--json` to get machine-readable results.** `generate`, `validate`, `infer` and `preview` accept `--json`: stdout then contains a single JSON object and nothing else (no panels, tables or colors).
+
+```
+fauxdata infer real.csv --out schema.yml --json
+{"schema_path": "schema.yml", "columns": ["id", "email", "age"], "validation_rules": 4}
+
+fauxdata generate schema.yml --out data.csv --validate --json
+{"output_path": "data.csv", "format": "csv", "rows": 1000, "seed": 42, "dry_run": false, "validation": {"passed": true, "results": [...]}}
+
+fauxdata validate data.csv schema.yml --json
+{"passed": true, "rows": 1000, "results": [{"step": 1, "rule": "col_vals_not_null", "column": "id", "passed": 1000, "failed": 0, "total": 1000, "ok": true, "evaluated": true}, ...]}
+```
+
+- Errors come back as `{"error": "..."}` on stdout with exit code `1`.
+- A step that could not run (for example, its column is missing from the data) has `"evaluated": false` and `"ok": false`; the human-readable table shows it as `NOT RUN`.
+- Exit codes: `0` success, `1` error or at least one validation rule failed.
+- `--json` cannot be combined with `--out -`, which already writes data (or YAML, for `infer`) to stdout.
+
+---
+
 ## Example schemas
 
 Three ready-to-use schemas are included in `schemas/`:

{fauxdata_cli-0.1.6 → fauxdata_cli-0.2.0}/README.md

@@ -146,12 +146,26 @@ validation:
 | Type | Description | Options |
 |------|-------------|---------|
 | `int` | Integer | `min`, `max`, `unique` |
-| `float` | Floating point | `min`, `max` |
+| `float` | Floating point | `min`, `max`, `precision` |
 | `string` | Text | `preset`, `values`, `pattern`, `unique`, `min_length`, `max_length` |
 | `bool` | Boolean | — |
 | `date` | Date | `min`, `max` (ISO format) |
 | `datetime` | Datetime | `min`, `max` (ISO format) |
 
+### Float precision
+
+`precision` sets the number of decimal places of a `float` column, e.g. `precision: 2` for prices:
+
+```yaml
+price:
+  type: float
+  min: 1.0
+  max: 199.999
+  precision: 2
+```
+
+Rounding never pushes a value outside `min`/`max`. When a bound has more decimals than `precision`, fauxdata moves it inward to the nearest value that fits: in the example above `max: 199.999` becomes `199.99`, so no generated price can round up to `200.00`. If no value with the requested decimals fits between `min` and `max` (e.g. `min: 1.001`, `max: 1.009`, `precision: 2`), `generate` stops with an error instead of producing out-of-range data. With `unique: true`, values are unique after rounding.
+
 ### String presets
 
 Presets generate realistic, locale-aware values. Set `locale` at the schema level to control the country.
@@ -206,6 +220,7 @@ Supported locales include: `US`, `IT`, `DE`, `FR`, `ES`, `JP`, `BR`, `PL`, `NL`,
 | `col_vals_between` | Value in range | `column`, `min`, `max` |
 | `col_vals_regex` | Matches pattern | `column`, `pattern` |
 | `col_vals_in_set` | Value in allowed set | `column`, `values` |
+| `col_vals_str_len` | String length in range (nulls are ignored) | `column`, `min` and/or `max` |
 | `col_vals_gt` / `col_vals_lt` | Greater / less than | `column`, `min` / `max` |
 | `col_vals_ge` / `col_vals_le` | Greater / less or equal | `column`, `min` / `max` |
 | `rows_distinct` | Unique rows | `columns` |
@@ -232,6 +247,7 @@ fauxdata generate schemas/people.yml --out - --format jsonl | wc -l
 | `--format` | `-f` | from schema | Output format: `csv`, `parquet`, `json`, `jsonl`, `jsonlines` |
 | `--seed` | `-s` | from schema | Random seed for reproducibility |
 | `--validate` | `-v` | off | Run validation rules after generating |
+| `--json` | | off | Print only a JSON summary to stdout (see [Using fauxdata with AI agents](#using-fauxdata-with-ai-agents)) |
 
 When `--out -` is used, all output messages are suppressed and only data is written to stdout.
 
@@ -293,6 +309,36 @@ Interactive wizard to create a new schema template. Asks for name, description,
 
 ---
 
+## Using fauxdata with AI agents
+
+fauxdata is designed to be driven by AI agents as well as by people.
+
+**Start with `fauxdata agent`.** It prints a Markdown guide with everything an agent needs to use the tool without reading this README: the workflow, the schema format, column types and options, presets, validation rules, the JSON output of each command, exit codes and a complete example schema. The lists of types, presets and rules are built from the code, so the guide always matches the installed version.
+
+```
+fauxdata agent > fauxdata-guide.md
+```
+
+**Add `--json` to get machine-readable results.** `generate`, `validate`, `infer` and `preview` accept `--json`: stdout then contains a single JSON object and nothing else (no panels, tables or colors).
+
+```
+fauxdata infer real.csv --out schema.yml --json
+{"schema_path": "schema.yml", "columns": ["id", "email", "age"], "validation_rules": 4}
+
+fauxdata generate schema.yml --out data.csv --validate --json
+{"output_path": "data.csv", "format": "csv", "rows": 1000, "seed": 42, "dry_run": false, "validation": {"passed": true, "results": [...]}}
+
+fauxdata validate data.csv schema.yml --json
+{"passed": true, "rows": 1000, "results": [{"step": 1, "rule": "col_vals_not_null", "column": "id", "passed": 1000, "failed": 0, "total": 1000, "ok": true, "evaluated": true}, ...]}
+```
+
+- Errors come back as `{"error": "..."}` on stdout with exit code `1`.
+- A step that could not run (for example, its column is missing from the data) has `"evaluated": false` and `"ok": false`; the human-readable table shows it as `NOT RUN`.
+- Exit codes: `0` success, `1` error or at least one validation rule failed.
+- `--json` cannot be combined with `--out -`, which already writes data (or YAML, for `infer`) to stdout.
+
+---
+
 ## Example schemas
 
 Three ready-to-use schemas are included in `schemas/`:

fauxdata_cli-0.2.0/RELEASING.md

@@ -0,0 +1,83 @@
+# Releasing
+
+Procedura per pubblicare una nuova release di `fauxdata` su PyPI.
+Il deploy **non è automatico**: nessun workflow GitHub Actions. Ogni step è manuale.
+
+## Versioning
+
+`MAJOR.MINOR.PATCH` (SemVer).
+
+- **subrelease / patch** (`0.1.5` → `0.1.6`): bugfix, nessuna modifica di API.
+- **minor** (`0.1.x` → `0.2.0`): nuove feature retrocompatibili.
+- **major** (`0.x` → `1.0.0`): breaking change.
+
+## Step
+
+1. **Aggiorna la versione** nei due file (devono restare allineati):
+   - `pyproject.toml` → `version = "X.Y.Z"`
+   - `src/fauxdata/__init__.py` → `__version__ = "X.Y.Z"`
+
+2. **Aggiorna `LOG.md`**: nuova sezione in cima con data `YYYY-MM-DD` e le modifiche.
+
+3. **Test**: devono passare tutti.
+
+   ```bash
+   uv run pytest tests/ -q
+   uv run fauxdata --version   # deve stampare la nuova versione
+   ```
+
+4. **Build**:
+
+   ```bash
+   rm -rf dist/
+   uv build
+   ls dist/   # fauxdata_cli-X.Y.Z-py3-none-any.whl + .tar.gz
+   ```
+
+5. **Aggiorna la CLI installata localmente** (`fauxdata` è installato come `uv tool`):
+
+   ```bash
+   uv tool install --reinstall .   # reinstalla dalla working copy
+   fauxdata --version              # deve stampare la nuova versione
+   ```
+
+6. **Commit + tag + push**:
+
+   ```bash
+   git add pyproject.toml src/fauxdata/__init__.py LOG.md
+   git commit -m "chore: vX.Y.Z — <sintesi>"
+   git tag -a vX.Y.Z -m "vX.Y.Z — <sintesi>"
+   git push origin main
+   git push origin vX.Y.Z
+   ```
+
+7. **Pubblica su PyPI** (richiede token PyPI — step da eseguire a mano):
+
+   ```bash
+   uv publish              # oppure: twine upload dist/*
+   ```
+
+   Il token si passa via `UV_PUBLISH_TOKEN` o `--token`. Non committare mai il token.
+
+8. **Verifica / aggiorna da PyPI** (il pacchetto su PyPI è `fauxdata-cli`):
+
+   ```bash
+   uvx fauxdata@X.Y.Z --version          # verifica al volo la versione pubblicata
+
+   pip install --upgrade fauxdata-cli     # aggiorna un'installazione pip esistente
+   # oppure, se installato come uv tool:
+   uv tool upgrade fauxdata-cli
+   ```
+
+9. **GitHub Release**: dal tag già pushato (il tag da solo **non** crea la release).
+   **Titolo e note devono essere in inglese.**
+
+   ```bash
+   gh release create vX.Y.Z --title "vX.Y.Z" --notes "<changelog in English>"
+   ```
+
+## Note
+
+- Se una release chiude una issue, referenziarla nel commit/tag (`#N`) e chiudere la issue con un commento che linka al commit.
+- La versione è testata dinamicamente (`test_cli_version` legge `__version__`), quindi il bump non rompe i test.
+- **Tag ≠ GitHub Release**: `git push origin vX.Y.Z` crea solo il tag; la pagina di release va creata a parte con `gh release create` (step 9).

fauxdata_cli-0.2.0/docs/future-ideas.md

@@ -0,0 +1,8 @@
+# Future ideas
+
+Ideas from the pointblank 0.26-1.0.1 releases, not yet planned (2026-10-11).
+
+- Related tables: generate linked datasets (e.g. people and orders) and check foreign keys with `col_vals_in_table()` (pointblank 0.27).
+- Coded missing values: a schema field for sentinel values like `-99` or `N/A`, generated and validated via `MissingSpec` and `col_pct_missing()` (pointblank 0.26).
+- Schema export: let `infer` also write JSON Schema, Frictionless, dbt or ODCS via `export_contract()` (pointblank 0.26/0.27).
+- Fidelity report: compare the real dataset with the synthetic one using `DataScan.compare()` (PSI, Kolmogorov-Smirnov) to show how close the shapes are (pointblank 0.27).

{fauxdata_cli-0.1.6 → fauxdata_cli-0.2.0}/docs/index.html

@@ -788,7 +788,7 @@
     </div>
 
     <div class="badges" aria-label="Technologies used">
-      <span class="badge green">pointblank 0.22+</span>
+      <span class="badge green">pointblank 1.0+</span>
       <span class="badge green">polars</span>
       <span class="badge amber">python 3.11+</span>
       <span class="badge blue">100+ locales</span>
@@ -858,7 +858,7 @@
 <section id="commands" aria-labelledby="commands-heading">
   <div class="container">
     <p class="section-label" aria-hidden="true">// the commands</p>
-    <h2 id="commands-heading">four commands.<br>one tool.</h2>
+    <h2 id="commands-heading">six commands.<br>one tool.</h2>
 
     <div class="table-wrap">
       <table>
@@ -871,11 +871,15 @@
         <tbody>
           <tr>
             <td><code>fauxdata generate SCHEMA</code></td>
-            <td>Generate a dataset from a YAML schema. Options: <code>--rows</code>, <code>--format</code>, <code>--seed</code>, <code>--out -</code> (stdout), <code>--validate</code></td>
+            <td>Generate a dataset from a YAML schema. Options: <code>--rows</code>, <code>--format</code>, <code>--seed</code>, <code>--out -</code> (stdout), <code>--validate</code>, <code>--json</code></td>
           </tr>
           <tr>
             <td><code>fauxdata validate DATASET SCHEMA</code></td>
-            <td>Validate an existing file against a schema. Exits with code 1 on failure — CI-ready.</td>
+            <td>Validate an existing file against a schema. Exits with code 1 on failure — CI-ready. Add <code>--json</code> for machine-readable results.</td>
+          </tr>
+          <tr>
+            <td><code>fauxdata infer DATASET</code></td>
+            <td>Build a YAML schema from a real dataset: ranges, categories, presets, null rates, plus matching validation rules. Generate look-alike data without shipping the real values.</td>
           </tr>
           <tr>
             <td><code>fauxdata preview DATASET</code></td>
@@ -885,6 +889,10 @@
             <td><code>fauxdata init [--name]</code></td>
             <td>Interactive wizard to create a new schema template.</td>
           </tr>
+          <tr>
+            <td><code>fauxdata agent</code></td>
+            <td>Print a Markdown guide for AI agents: workflow, schema format, presets, rules, JSON output. <code>generate</code>, <code>validate</code>, <code>infer</code> and <code>preview</code> also speak <code>--json</code>.</td>
+          </tr>
         </tbody>
       </table>
     </div>

{fauxdata_cli-0.1.6 → fauxdata_cli-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fauxdata-cli"
-version = "0.1.6"
+version = "0.2.0"
 description = "CLI for generating and validating fake datasets"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -13,7 +13,7 @@ classifiers = [
     "Operating System :: OS Independent",
 ]
 dependencies = [
-    "pointblank>=0.25",
+    "pointblank>=1.0.1",
     "typer>=0.12",
     "rich>=13",
     "pyfiglet>=1.0",

{fauxdata_cli-0.1.6 → fauxdata_cli-0.2.0}/src/fauxdata/__init__.py

@@ -1,3 +1,3 @@
 """fauxdata - CLI for generating and validating fake datasets."""
 
-__version__ = "0.1.6"
+__version__ = "0.2.0"

fauxdata_cli-0.2.0/src/fauxdata/commands/agent.py

@@ -0,0 +1,160 @@
+"""fauxdata agent command - a Markdown guide for AI agents.
+
+The lists of column types, presets and validation rules are built from the
+constants in ``fauxdata.schema``, so the guide cannot drift from the code.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from fauxdata import __version__
+from fauxdata.schema import STRING_PRESETS, VALID_RULES, VALID_TYPES
+
+TYPE_OPTIONS = {
+    "int": "`min`, `max`, `unique`, `values`",
+    "float": "`min`, `max`, `precision`, `unique`, `values`",
+    "string": "`preset`, `values`, `pattern`, `unique`, `min_length`, `max_length`",
+    "bool": "-",
+    "date": "`min`, `max` (ISO date), `unique`",
+    "datetime": "`min`, `max` (ISO datetime), `unique`",
+}
+
+RULE_PARAMS = {
+    "col_vals_not_null": ("`columns`", "no nulls"),
+    "col_vals_between": ("`column`, `min`, `max`", "value in range"),
+    "col_vals_gt": ("`column`, `min`", "value > min"),
+    "col_vals_lt": ("`column`, `max`", "value < max"),
+    "col_vals_ge": ("`column`, `min`", "value >= min"),
+    "col_vals_le": ("`column`, `max`", "value <= max"),
+    "col_vals_regex": ("`column`, `pattern`", "value matches the regex"),
+    "col_vals_in_set": ("`column`, `values`", "value in the allowed set"),
+    "col_vals_str_len": ("`column`, `min` and/or `max`", "string length in range"),
+    "rows_distinct": ("`columns`", "no duplicate keys (rows with a null key are skipped)"),
+    "col_exists": ("`columns`", "column present"),
+}
+
+EXAMPLE = """\
+name: people
+rows: 1000
+seed: 42
+locale: IT
+output:
+  format: csv
+  path: people.csv
+columns:
+  id:
+    type: int
+    unique: true
+    min: 1
+    max: 99999
+  name:
+    type: string
+    preset: name
+  email:
+    type: string
+    preset: email
+  age:
+    type: int
+    min: 18
+    max: 90
+    null_probability: 0.05
+  score:
+    type: float
+    min: 0
+    max: 100
+    precision: 1
+  status:
+    type: string
+    values: [active, inactive, pending]
+validation:
+  - rule: col_vals_not_null
+    columns: [id, name, email]
+  - rule: col_vals_between
+    column: age
+    min: 18
+    max: 90
+  - rule: col_vals_in_set
+    column: status
+    values: [active, inactive, pending]
+  - rule: rows_distinct
+    columns: [id]
+"""
+
+
+def guide() -> str:
+    types = "\n".join(f"| `{t}` | {TYPE_OPTIONS.get(t, '-')} |" for t in sorted(VALID_TYPES))
+    rules = "\n".join(
+        f"| `{r}` | {RULE_PARAMS.get(r, ('-', '-'))[0]} | {RULE_PARAMS.get(r, ('-', '-'))[1]} |"
+        for r in sorted(VALID_RULES)
+    )
+    presets = ", ".join(f"`{p}`" for p in sorted(STRING_PRESETS))
+    return f"""# fauxdata {__version__} - guide for AI agents
+
+fauxdata generates realistic fake datasets from a YAML schema and validates datasets against the same schema.
+
+## Workflow
+
+1. Write a schema (see the example below), or infer one from a real table:
+   `fauxdata infer real.csv --out schema.yml --json`
+2. Generate data and validate it in one step:
+   `fauxdata generate schema.yml --out data.csv --validate --json`
+3. Validate any existing file against a schema:
+   `fauxdata validate data.csv schema.yml --json`
+4. Inspect a file (column stats and first rows):
+   `fauxdata preview data.csv --json`
+
+## Machine-readable output
+
+- With `--json`, stdout contains exactly one JSON object and nothing else.
+- On error: `{{"error": "..."}}` on stdout, exit code 1.
+- `validate --json`: `{{"passed": bool, "rows": int, "results": [{{"step", "rule", "column", "passed", "failed", "total", "ok", "evaluated"}}]}}`
+- `generate --json`: `{{"output_path", "format", "rows", "seed", "dry_run", "validation": null | {{"passed", "results"}}}}`
+- `infer --json`: `{{"schema_path", "columns": [names], "validation_rules": int}}`
+- `preview --json`: `{{"rows", "columns": [{{"name", "type", "nulls", "unique", "min", "max"}}], "head": [rows]}}`
+- `evaluated: false` means the step could not run (e.g. its column is missing from the data); such a step has `ok: false`.
+- `--json` cannot be combined with `--out -` (that mode writes data or YAML to stdout).
+
+## Exit codes
+
+- `0`: success, all validation rules passed
+- `1`: error, or at least one validation rule failed
+
+## Schema
+
+Top-level keys: `name` (required), `columns` (required), `rows`, `seed`, `locale` (ISO country code, e.g. `US`, `IT`, `DE`, `JP`), `description`, `output.format` (`csv`, `parquet`, `json`, `jsonl`), `output.path`, `validation`.
+
+Every column needs `type`. Any column also accepts `nullable` and `null_probability` (0-1).
+
+| Type | Options |
+|------|---------|
+{types}
+
+Notes:
+- `precision` rounds floats; bounds with more decimals are moved inward so values never leave `min`/`max`.
+- `values` restricts a column to a fixed set (strings, ints or floats).
+- `pattern` generates strings matching a regex.
+
+### String presets
+
+{presets}
+
+Presets are locale-aware and coherent within a row (the email matches the name, the city matches the country). Known limit: `unique: true` is not enforced on person and address presets such as `name`, `email`, `user_name`, `city` (pointblank issue #441). Validate with `rows_distinct` if uniqueness matters.
+
+## Validation rules
+
+| Rule | Parameters | Checks |
+|------|------------|--------|
+{rules}
+
+Value rules ignore nulls: use `col_vals_not_null` to forbid them.
+
+## Example schema
+
+```yaml
+{EXAMPLE}```
+"""
+
+
+def run():
+    sys.stdout.write(guide())

{fauxdata_cli-0.1.6 → fauxdata_cli-0.2.0}/src/fauxdata/commands/generate.py

@@ -11,6 +11,7 @@ from rich.console import Console
 from rich.panel import Panel
 from rich.table import Table
 
+from fauxdata import jsonmode
 from fauxdata.generator import generate_dataset
 from fauxdata.output import default_output_path, export_dataset, write_stdout
 from fauxdata.schema import load_schema
@@ -19,11 +20,13 @@ from fauxdata.validator import validate_dataset
 console = Console()
 
 
-def _generate(schema, n, rng_seed):
+def _generate(schema, n, rng_seed, json_out=False):
     """Generate, translating generation errors into a clean CLI exit."""
     try:
         return generate_dataset(schema, rows=n, seed=rng_seed)
     except ValueError as e:
+        if json_out:
+            jsonmode.fail(str(e))
         rprint(f"[red]Error:[/red] {e}")
         raise typer.Exit(code=1)
 
@@ -36,6 +39,7 @@ def run(
     seed: Optional[int] = None,
     validate: bool = False,
     dry_run: bool = False,
+    json_out: bool = False,
 ):
     """Generate a fake dataset from a YAML schema."""
     schema = load_schema(schema_path)
@@ -47,6 +51,10 @@ def run(
 
     stdout_mode = output_path == "-"
 
+    if json_out:
+        _run_json(schema, n, rng_seed, output_fmt, output_path, validate, dry_run)
+        return
+
     if dry_run:
         rprint(Panel(f"[bold cyan]fauxdata generate --dry-run[/bold cyan]  [dim]{schema_path}[/dim]", expand=False))
         rprint("[yellow]Dry run — no files will be written.[/yellow]\n")
@@ -81,6 +89,25 @@ def run(
         _run_validation(df, schema)
 
 
+def _run_json(schema, n, rng_seed, output_fmt, output_path, validate, dry_run):
+    if output_path == "-":
+        jsonmode.fail("--json cannot be combined with --out - (the data would go to stdout)")
+    summary = {"output_path": output_path, "format": output_fmt, "rows": n, "seed": rng_seed,
+               "dry_run": dry_run, "validation": None}
+    if dry_run:
+        jsonmode.emit(summary)
+        return
+    df = _generate(schema, n, rng_seed, json_out=True)
+    summary["output_path"] = str(export_dataset(df, output_path, output_fmt))
+    passed = True
+    if validate:
+        passed, results = validate_dataset(df, schema)
+        summary["validation"] = {"passed": passed, "results": results}
+    jsonmode.emit(summary)
+    if not passed:
+        raise typer.Exit(code=1)
+
+
 def _print_schema_table(schema, n: int, seed):
     t = Table(title=f"Schema: {schema.name}", show_header=True, header_style="bold magenta")
     t.add_column("Column", style="cyan")
@@ -132,7 +159,12 @@ def _run_validation(df, schema):
     t.add_column("Status")
 
     for r in results:
-        status = "[green]PASS[/green]" if r["ok"] else "[red]FAIL[/red]"
+        if r["ok"]:
+            status = "[green]PASS[/green]"
+        elif not r["evaluated"]:
+            status = "[red]NOT RUN[/red]"
+        else:
+            status = "[red]FAIL[/red]"
         t.add_row(
             str(r["step"]),
             r["rule"],