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

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: fauxdata-cli
-Version: 0.1.6
+Version: 0.2.1
 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.1.0
 Requires-Dist: polars>=1.0
 Requires-Dist: pyfiglet>=1.0
 Requires-Dist: pyyaml>=6.0
@@ -93,7 +93,7 @@ fauxdata init --name orders
 
 ## Schema format
 
-A schema is a YAML file that describes the structure of your dataset. Here is a realistic example for a people dataset:
+A schema is a YAML file that describes the structure of your dataset. Here is a realistic example for a people dataset, adapted from [`schemas/people.yml`](https://github.com/aborruso/fauxdata/blob/main/schemas/people.yml):
 
 ```yaml
 name: people
@@ -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,15 +333,45 @@ 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/`:
+Three ready-to-use schemas are included in [`schemas/`](https://github.com/aborruso/fauxdata/tree/main/schemas):
 
 | Schema | Domain | Columns |
 |--------|--------|---------|
-| `people.yml` | Personal data | id, name, email, age, city, country_code, active, signup_date, score |
-| `orders.yml` | E-commerce | order_id, customer_id, product, amount, status, created_at |
-| `events.yml` | Analytics | event_id, user_id, event_type, timestamp, ip, user_agent, session_duration |
+| [`people.yml`](https://github.com/aborruso/fauxdata/blob/main/schemas/people.yml) | Personal data | id, name, email, age, city, country_code, active, signup_date, score |
+| [`orders.yml`](https://github.com/aborruso/fauxdata/blob/main/schemas/orders.yml) | E-commerce | order_id, customer_id, product, amount, status, created_at |
+| [`events.yml`](https://github.com/aborruso/fauxdata/blob/main/schemas/events.yml) | Analytics | event_id, user_id, event_type, timestamp, ip, user_agent, session_duration |
 
 ---
 

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

@@ -69,7 +69,7 @@ fauxdata init --name orders
 
 ## Schema format
 
-A schema is a YAML file that describes the structure of your dataset. Here is a realistic example for a people dataset:
+A schema is a YAML file that describes the structure of your dataset. Here is a realistic example for a people dataset, adapted from [`schemas/people.yml`](https://github.com/aborruso/fauxdata/blob/main/schemas/people.yml):
 
 ```yaml
 name: people
@@ -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,15 +309,45 @@ 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/`:
+Three ready-to-use schemas are included in [`schemas/`](https://github.com/aborruso/fauxdata/tree/main/schemas):
 
 | Schema | Domain | Columns |
 |--------|--------|---------|
-| `people.yml` | Personal data | id, name, email, age, city, country_code, active, signup_date, score |
-| `orders.yml` | E-commerce | order_id, customer_id, product, amount, status, created_at |
-| `events.yml` | Analytics | event_id, user_id, event_type, timestamp, ip, user_agent, session_duration |
+| [`people.yml`](https://github.com/aborruso/fauxdata/blob/main/schemas/people.yml) | Personal data | id, name, email, age, city, country_code, active, signup_date, score |
+| [`orders.yml`](https://github.com/aborruso/fauxdata/blob/main/schemas/orders.yml) | E-commerce | order_id, customer_id, product, amount, status, created_at |
+| [`events.yml`](https://github.com/aborruso/fauxdata/blob/main/schemas/events.yml) | Analytics | event_id, user_id, event_type, timestamp, ip, user_agent, session_duration |
 
 ---
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "fauxdata-cli"
-version = "0.1.6"
+version = "0.2.1"
 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.1.0",
     "typer>=0.12",
     "rich>=13",
     "pyfiglet>=1.0",
@@ -46,3 +46,6 @@ build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/fauxdata"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src", "tests", "schemas", "README.md", "LICENSE", "pyproject.toml"]

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

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

fauxdata_cli-0.2.1/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).
+
+## 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.1}/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"],

{fauxdata_cli-0.1.6 → fauxdata_cli-0.2.1}/src/fauxdata/commands/infer.py

@@ -14,6 +14,8 @@ import pointblank as pb
 import polars as pl
 import typer
 import yaml
+
+from fauxdata import jsonmode
 from rich import print as rprint
 from rich.panel import Panel
 
@@ -98,6 +100,13 @@ def _build_validation(columns: list[tuple[str, dict]]) -> list[dict]:
         if "values" in spec:
             rules.append({"rule": "col_vals_in_set", "column": name, "values": list(spec["values"])})
 
+    for name, spec in columns:
+        # only free-text columns: the generator ignores lengths for preset/pattern/values
+        free_text = not any(k in spec for k in ("preset", "pattern", "values"))
+        if spec["type"] == "string" and free_text and ("min_length" in spec or "max_length" in spec):
+            rules.append({"rule": "col_vals_str_len", "column": name,
+                          "min": spec.get("min_length"), "max": spec.get("max_length")})
+
     unique_cols = [name for name, spec in columns if spec.get("unique")]
     if unique_cols:
         rules.append({"rule": "rows_distinct", "columns": unique_cols})
@@ -105,7 +114,7 @@ def _build_validation(columns: list[tuple[str, dict]]) -> list[dict]:
     return rules
 
 
-def _load_table(path: str) -> pl.DataFrame:
+def _load_table(path: str, json_out: bool = False) -> pl.DataFrame:
     ext = path.rsplit(".", 1)[-1].lower()
     if ext == "csv":
         # try_parse_dates so date/datetime columns are typed (not frozen as categorical strings)
@@ -116,10 +125,17 @@ def _load_table(path: str) -> pl.DataFrame:
         return pl.read_json(path)
     if ext in ("jsonl", "ndjson"):
         return pl.read_ndjson(path)
+    if json_out:
+        jsonmode.fail(f"Unsupported file format: .{ext}")
     rprint(f"[red]Unsupported file format: .{ext}[/red]")
     raise typer.Exit(code=1)
 
 
+def _threshold(value: float) -> int | float:
+    """pointblank reads a float as a fraction of rows: whole numbers >= 1 are counts."""
+    return int(value) if value >= 1 and float(value).is_integer() else value
+
+
 def run(
     dataset_path: str,
     out: str | None = None,
@@ -129,19 +145,24 @@ def run(
     categorical_threshold: float = 20,
     detect_presets: bool = True,
     sample_size: int | None = None,
+    json_out: bool = False,
 ):
     """Infer a fauxdata YAML schema from a real dataset."""
-    rprint(Panel(
-        f"[bold cyan]fauxdata infer[/bold cyan]  [dim]{dataset_path}[/dim]",
-        expand=False,
-    ))
-
-    df = _load_table(dataset_path)
-    rprint(f"  Loaded [bold]{len(df)}[/bold] rows, [bold]{len(df.columns)}[/bold] columns")
+    if json_out and out == "-":
+        jsonmode.fail("--json cannot be combined with --out - (the YAML would go to stdout)")
+    if not json_out:
+        rprint(Panel(
+            f"[bold cyan]fauxdata infer[/bold cyan]  [dim]{dataset_path}[/dim]",
+            expand=False,
+        ))
+
+    df = _load_table(dataset_path, json_out)
+    if not json_out:
+        rprint(f"  Loaded [bold]{len(df)}[/bold] rows, [bold]{len(df.columns)}[/bold] columns")
 
     pb_schema = pb.schema_from_tbl(
         df,
-        categorical_threshold=categorical_threshold,
+        categorical_threshold=_threshold(categorical_threshold),
         detect_presets=detect_presets,
         sample_size=sample_size,
     )
@@ -170,6 +191,13 @@ def run(
         return
 
     Path(out_path).write_text(text)
+    if json_out:
+        jsonmode.emit({
+            "schema_path": out_path,
+            "columns": [col_name for col_name, _ in columns],
+            "validation_rules": len(schema_dict["validation"]),
+        })
+        return
     rprint(f"[green]Created[/green] [bold]{out_path}[/bold] "
            f"([bold]{len(columns)}[/bold] columns, "
            f"[bold]{len(schema_dict['validation'])}[/bold] validation rules)")