sieve-crowd 0.2.0__py3-none-any.whl

sieve_crowd/__init__.py

@@ -0,0 +1,16 @@
+"""Sieve Crowd: make every record one of a crowd, and measure it.
+
+Deterministic, offline, zero-dependency k-anonymity (with optional l-diversity)
+for CSV, JSON and XML tables.
+"""
+
+__version__ = "0.2.0"
+
+from .config import Config, parse_config, parse_key  # noqa: E402
+from .engine import Result, anonymize, inspect_table  # noqa: E402
+from .model import ConfigError, InputError, Role  # noqa: E402
+
+__all__ = [
+    "__version__", "anonymize", "inspect_table", "Result", "Config", "parse_config", "parse_key",
+    "ConfigError", "InputError", "Role",
+]

sieve_crowd/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

sieve_crowd/cli.py

@@ -0,0 +1,206 @@
+"""Command line: inspect / keygen / run.  Cell values never appear in messages or logs."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import secrets
+import sys
+import tempfile
+from typing import Optional, Sequence
+
+from . import __version__
+from .config import parse_config, parse_key
+from .engine import anonymize, inspect_table
+from .hints import hint
+from .model import ConfigError, InputError
+from .tableio import FORMATS, detect_format, read_any, write_any
+
+EXIT_OK, EXIT_IO, EXIT_CONFIG, EXIT_REFUSED = 0, 1, 2, 3
+
+
+def _atomic_write(path: str, data: bytes, private: bool = False) -> None:
+    directory = os.path.dirname(os.path.abspath(path))
+    fd, tmp = tempfile.mkstemp(dir=directory, prefix=".sieve-crowd-")
+    try:
+        with os.fdopen(fd, "wb") as fh:
+            fh.write(data)
+        if private:
+            os.chmod(tmp, 0o600)
+        os.replace(tmp, path)
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def _parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="sieve-crowd",
+                                description="Make every record one of a crowd of at least k, and measure it.")
+    p.add_argument("--version", action="version", version=f"sieve-crowd {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    i = sub.add_parser("inspect", help="describe the columns of a table (csv, json or xml) and write a config template")
+    i.add_argument("input")
+    i.add_argument("--delimiter", help="CSV only")
+    i.add_argument("--in-format", choices=FORMATS,
+                   help="force the input format (default: from the file extension)")
+    i.add_argument("--lang", choices=["en", "ja"], default="en")
+    i.add_argument("--config-out", metavar="FILE", help="write a template with role '?' for every column")
+    i.add_argument("--force", action="store_true")
+
+    k = sub.add_parser("keygen", help="create a key for pseudonyms")
+    k.add_argument("-o", "--output", required=True)
+    k.add_argument("--force", action="store_true")
+
+    r = sub.add_parser("run", help="anonymize a table (csv, json or xml)")
+    r.add_argument("input")
+    r.add_argument("-c", "--config", required=True)
+    r.add_argument("-o", "--output")
+    r.add_argument("--dry-run", action="store_true", help="measure only; write no table")
+    r.add_argument("--delimiter", help="CSV only")
+    r.add_argument("--in-format", choices=FORMATS,
+                   help="force the input format (default: from the file extension)")
+    r.add_argument("--out-format", choices=FORMATS,
+                   help="force the output format (default: from the output extension)")
+    r.add_argument("--key-file")
+    r.add_argument("--k", type=int)
+    r.add_argument("--l", type=int)
+    r.add_argument("--max-suppression", type=float)
+    r.add_argument("--keep-order", action="store_true", help="relaxation: do not shuffle the rows (recorded)")
+    r.add_argument("--shuffle-seed", type=int, default=0)
+    r.add_argument("--lang", choices=["en", "ja"], default="en")
+    r.add_argument("--max-rows", type=int, default=200_000)
+    r.add_argument("--max-evals", type=int, default=20_000)
+    r.add_argument("--report-json", metavar="FILE")
+    r.add_argument("--quiet", action="store_true")
+    r.add_argument("--force", action="store_true")
+    return p
+
+
+def _read(path: str) -> bytes:
+    if path == "-":
+        return sys.stdin.buffer.read()
+    with open(path, "rb") as fh:
+        return fh.read()
+
+
+def _resolve_format(path: str, explicit: Optional[str], *, dash_default: str) -> str:
+    if explicit:
+        return explicit
+    if path == "-":
+        return dash_default
+    return detect_format(os.path.splitext(path)[1])
+
+
+def _delimiter(given: Optional[str], sides: set[str]) -> Optional[str]:
+    if given is None:
+        return None
+    if sides - {"csv"}:
+        raise InputError("--delimiter applies to csv only (the table is json/xml)")
+    return given
+
+
+def _cmd_inspect(a: argparse.Namespace) -> int:
+    try:
+        in_fmt = _resolve_format(a.input, a.in_format, dash_default="csv")
+        delim = _delimiter(a.delimiter, {in_fmt})
+        header, rows = read_any(_read(a.input), in_fmt, delim)
+    except InputError as exc:
+        print(f"error: {exc}", file=sys.stderr); return EXIT_CONFIG
+    except OSError as exc:
+        print(f"error: cannot read the input ({exc.strerror})", file=sys.stderr); return EXIT_IO
+    info = inspect_table(header, rows)
+    en = a.lang == "en"
+    print(f"records: {len(rows)}" if en else f"レコード数: {len(rows)}")
+    hints = {}
+    for c in info:
+        role, text_en, text_ja = hint(c["name"], c, len(rows))
+        hints[c["name"]] = (role, text_en if en else text_ja)
+        shown = f"  {c['name']}: {c['distinct']} distinct, {c['empty']} empty, {c['unique_ratio']:.0%} unique values, looks like {c['shape']}" \
+            if en else f"  {c['name']}: 異なる値 {c['distinct']}、空 {c['empty']}、一意な値 {c['unique_ratio']:.0%}、形は {c['shape']}"
+        print(shown)
+        if role:
+            print(f"      -> {hints[c['name']][1]}")
+    if a.config_out:
+        if os.path.exists(a.config_out) and not a.force:
+            print("error: the config file exists (use --force)", file=sys.stderr); return EXIT_IO
+        template = {"k": 5, "l": 1, "max_suppression": 0.05,
+                    "columns": {c["name"]: ({"role": "?", "_hint": hints[c["name"]][1]} if hints[c["name"]][0]
+                                    else {"role": "?"}) for c in info}}
+        try:
+            _atomic_write(a.config_out, (json.dumps(template, ensure_ascii=False, indent=2) + "\n").encode())
+        except OSError as exc:
+            print(f"error: cannot write ({exc.strerror})", file=sys.stderr); return EXIT_IO
+    return EXIT_OK
+
+
+def _cmd_keygen(a: argparse.Namespace) -> int:
+    if os.path.exists(a.output) and not a.force:
+        print("error: the key file exists (use --force)", file=sys.stderr); return EXIT_IO
+    try:
+        _atomic_write(a.output, (secrets.token_hex(32) + "\n").encode(), private=True)
+    except OSError as exc:
+        print(f"error: cannot write ({exc.strerror})", file=sys.stderr); return EXIT_IO
+    return EXIT_OK
+
+
+def _cmd_run(a: argparse.Namespace) -> int:
+    if not a.dry_run and not a.output:
+        print("error: give -o/--output or --dry-run", file=sys.stderr); return EXIT_CONFIG
+    if a.output and a.input != "-" and os.path.realpath(a.output) == os.path.realpath(a.input):
+        print("error: the output must not be the input file", file=sys.stderr); return EXIT_CONFIG
+    if a.output and os.path.exists(a.output) and not a.force:
+        print("error: output exists (use --force to replace it)", file=sys.stderr); return EXIT_IO
+    try:
+        in_fmt = _resolve_format(a.input, a.in_format, dash_default="csv")
+        out_fmt = _resolve_format(a.output, a.out_format, dash_default="csv") if a.output else None
+        delim = _delimiter(a.delimiter, {in_fmt} | (set() if out_fmt is None else {out_fmt}))
+    except InputError as exc:
+        print(f"error: {exc}", file=sys.stderr); return EXIT_CONFIG
+    try:
+        with open(a.config, "rb") as fh:
+            raw = json.loads(fh.read().decode("utf-8-sig"))
+        key = parse_key(open(a.key_file, encoding="utf-8").read()) if a.key_file else None
+        cfg = parse_config(raw, k=a.k, l=a.l, max_suppression=a.max_suppression,
+                           shuffle=not a.keep_order, shuffle_seed=a.shuffle_seed, lang=a.lang,
+                           max_rows=a.max_rows, max_evals=a.max_evals, key=key)
+    except ConfigError as exc:
+        print(f"error: {exc}", file=sys.stderr); return EXIT_CONFIG
+    except (json.JSONDecodeError, UnicodeDecodeError):
+        print("error: the configuration is not valid JSON", file=sys.stderr); return EXIT_CONFIG
+    except OSError as exc:
+        print(f"error: cannot read the configuration or key ({exc.strerror})", file=sys.stderr); return EXIT_IO
+    try:
+        header, rows = read_any(_read(a.input), in_fmt, delim)
+    except InputError as exc:
+        print(f"error: {exc}", file=sys.stderr); return EXIT_CONFIG
+    except OSError as exc:
+        print(f"error: cannot read the input ({exc.strerror})", file=sys.stderr); return EXIT_IO
+    try:
+        result = anonymize(header, rows, cfg, io=(in_fmt, out_fmt))
+    except ConfigError as exc:
+        print(f"error: {exc}", file=sys.stderr); return EXIT_CONFIG
+    if not a.quiet:
+        print(result.report.text(cfg.lang), file=sys.stderr)
+    try:
+        if a.report_json:
+            _atomic_write(a.report_json, (result.report.to_json() + "\n").encode("utf-8"))
+        if result.status == "refused":
+            return EXIT_REFUSED
+        if not a.dry_run:
+            data = write_any(result.header, result.rows, out_fmt, delim)
+            if a.output == "-":
+                sys.stdout.buffer.write(data); sys.stdout.buffer.flush()
+            else:
+                _atomic_write(a.output, data)
+    except OSError as exc:
+        print(f"error: cannot write ({exc.strerror})", file=sys.stderr); return EXIT_IO
+    return EXIT_OK
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    a = _parser().parse_args(argv)
+    return {"inspect": _cmd_inspect, "keygen": _cmd_keygen, "run": _cmd_run}[a.cmd](a)

sieve_crowd/config.py

@@ -0,0 +1,118 @@
+"""Configuration: which column plays which role, and how much to protect."""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any, Mapping, Optional
+
+from .generalize import make_generalizer
+from .model import ConfigError, Role
+
+_TOP_KEYS = {"k", "l", "max_suppression", "columns"}
+_COL_KEYS = {"role", "action", "type", "widths", "length", "hierarchy"}
+_HEX = re.compile(r"^[0-9a-fA-F]{32,}$")
+
+
+@dataclass(frozen=True)
+class ColumnSpec:
+    name: str
+    role: Role
+    action: str = "drop"                    # role id: "drop" | "pseudonymize"
+    gen: Optional[Mapping[str, Any]] = None  # role qi: generalizer settings
+
+
+@dataclass(frozen=True)
+class Config:
+    columns: Mapping[str, ColumnSpec]
+    k: int = 5
+    l: int = 1
+    max_suppression: float = 0.05
+    shuffle: bool = True            # keep-order is a relaxation, recorded in the report
+    shuffle_seed: int = 0
+    lang: str = "en"
+    max_rows: int = 200_000
+    max_evals: int = 20_000
+    key: Optional[bytes] = None
+
+    def names(self, role: Role) -> list[str]:
+        return [n for n, c in self.columns.items() if c.role is role]
+
+
+def parse_key(text: str) -> bytes:
+    t = text.strip()
+    if not _HEX.match(t):
+        raise ConfigError("the key must be at least 32 hexadecimal characters (see 'sieve-crowd keygen')")
+    return bytes.fromhex(t if len(t) % 2 == 0 else t[:-1])
+
+
+def parse_config(obj: Mapping[str, Any], **overrides: Any) -> Config:
+    if not isinstance(obj, Mapping):
+        raise ConfigError("the configuration must be a JSON object")
+    obj = {k: v for k, v in obj.items() if not str(k).startswith("_")}
+    unknown = set(obj) - _TOP_KEYS
+    if unknown:
+        raise ConfigError(f"unknown configuration key(s): {', '.join(sorted(unknown))}")
+    cols_raw = obj.get("columns")
+    if not isinstance(cols_raw, Mapping) or not cols_raw:
+        raise ConfigError("'columns' must list every column of the table with a role")
+
+    columns: dict[str, ColumnSpec] = {}
+    for name, spec in cols_raw.items():
+        if not isinstance(spec, Mapping):
+            raise ConfigError(f"column {name!r}: expected an object")
+        spec = {k: v for k, v in spec.items() if not str(k).startswith("_")}
+        extra = set(spec) - _COL_KEYS
+        if extra:
+            raise ConfigError(f"column {name!r}: unknown key(s): {', '.join(sorted(extra))}")
+        role_text = spec.get("role")
+        if role_text == "?" or role_text is None:
+            raise ConfigError(f"column {name!r} has no role yet (choose id, qi, sensitive, keep or drop)")
+        try:
+            role = Role(role_text)
+        except ValueError:
+            raise ConfigError(f"column {name!r}: unknown role {role_text!r}") from None
+        action, gen = "drop", None
+        if role is Role.ID:
+            action = spec.get("action", "drop")
+            if action not in ("drop", "pseudonymize"):
+                raise ConfigError(f"column {name!r}: action must be 'drop' or 'pseudonymize'")
+        if role is Role.QI:
+            gen = {k: v for k, v in spec.items() if k not in ("role", "action")}
+            make_generalizer(gen)  # validate now
+        columns[name] = ColumnSpec(name, role, action, gen)
+
+    def pick(key: str, default: Any) -> Any:
+        v = overrides.get(key)
+        return obj.get(key, default) if v is None else v
+
+    k = pick("k", 5)
+    l = pick("l", 1)
+    ms = pick("max_suppression", 0.05)
+    if not isinstance(k, int) or isinstance(k, bool) or k < 2:
+        raise ConfigError("k must be an integer >= 2")
+    if not isinstance(l, int) or isinstance(l, bool) or l < 1:
+        raise ConfigError("l must be an integer >= 1")
+    if not isinstance(ms, (int, float)) or isinstance(ms, bool) or not 0 <= ms < 1:
+        raise ConfigError("max_suppression must be a number in [0, 1)")
+
+    cfg = Config(
+        columns=columns, k=k, l=l, max_suppression=float(ms),
+        shuffle=overrides.get("shuffle", True),
+        shuffle_seed=overrides.get("shuffle_seed", 0),
+        lang=overrides.get("lang", "en"),
+        max_rows=overrides.get("max_rows", 200_000),
+        max_evals=overrides.get("max_evals", 20_000),
+        key=overrides.get("key"),
+    )
+    if not cfg.names(Role.QI):
+        raise ConfigError("at least one column needs the role 'qi' (what an outsider could already know)")
+    if cfg.l > 1 and not cfg.names(Role.SENSITIVE):
+        raise ConfigError("l > 1 needs at least one column with the role 'sensitive'")
+    if cfg.lang not in ("en", "ja"):
+        raise ConfigError("lang must be 'en' or 'ja'")
+    if any(c.role is Role.ID and c.action == "pseudonymize" for c in columns.values()) and cfg.key is None:
+        raise ConfigError("pseudonymize needs a key (create one with 'sieve-crowd keygen')")
+    for field, value in (("max_rows", cfg.max_rows), ("max_evals", cfg.max_evals)):
+        if not isinstance(value, int) or value < 1:
+            raise ConfigError(f"{field} must be a positive integer")
+    return cfg

sieve_crowd/csvio.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import csv
+import io
+
+from .model import InputError
+
+
+def read_table(data: bytes, delimiter: str = ",") -> tuple[list[str], list[list[str]]]:
+    """UTF-8 (BOM allowed) CSV with a header row."""
+    try:
+        text = data.decode("utf-8-sig")
+    except UnicodeDecodeError:
+        raise InputError("the input is not valid UTF-8") from None
+    try:
+        rows = list(csv.reader(io.StringIO(text, newline=""), delimiter=delimiter))
+    except csv.Error as exc:
+        raise InputError(f"the input is not valid CSV ({exc})") from None
+    if not rows or not rows[0]:
+        raise InputError("the input has no header row")
+    header, body = rows[0], rows[1:]
+    body = [r for r in body if r != []]  # blank lines
+    for i, r in enumerate(body, start=2):
+        if len(r) != len(header):
+            raise InputError(f"row {i} has {len(r)} fields, the header has {len(header)}")
+    return header, body
+
+
+def write_table(header: list[str], rows: list[list[str]], delimiter: str = ",") -> bytes:
+    buf = io.StringIO(newline="")
+    w = csv.writer(buf, delimiter=delimiter, lineterminator="\n")
+    w.writerow(header)
+    w.writerows(rows)
+    return buf.getvalue().encode("utf-8")

sieve_crowd/engine.py

@@ -0,0 +1,205 @@
+"""Orchestration: read roles -> generalize -> search -> suppress -> shuffle -> measure -> receipt."""
+from __future__ import annotations
+
+import math
+import re
+import unicodedata
+from dataclasses import dataclass
+from typing import Optional, Sequence
+
+from .config import Config
+from .generalize import Generalizer, make_generalizer
+from .measure import measure
+from .model import ConfigError, Role
+from .prng import SplitMix64
+from .pseudonym import pseudonym
+from .report import Report, base
+from .search import Infeasible, Searcher, SearchLimitExceeded
+
+
+@dataclass(frozen=True)
+class Result:
+    status: str                       # "anonymized" | "refused"
+    header: Optional[list[str]]
+    rows: Optional[list[list[str]]]
+    report: Report
+
+
+def _norm(v: str) -> str:
+    return unicodedata.normalize("NFC", v).strip()
+
+
+def _refuse(reason: str, n_in: int, cfg: Config,
+            io: Optional[tuple[str, Optional[str]]] = None) -> Result:
+    d = base("refused", reason=reason)
+    d["input"] = {"records": n_in}
+    _add_io(d, io)
+    return Result("refused", None, None, Report(d))
+
+
+def _add_io(d: dict, io: Optional[tuple[str, Optional[str]]]) -> None:
+    if io:
+        entry: dict = {"input_format": io[0]}
+        if io[1]:
+            entry["output_format"] = io[1]
+        d["io"] = entry
+
+
+def _check_columns(header: Sequence[str], cfg: Config) -> None:
+    if len(set(header)) != len(header):
+        raise ConfigError("the table has duplicate column names")
+    missing = [h for h in header if h not in cfg.columns]
+    if missing:
+        raise ConfigError(f"column(s) without a role: {', '.join(missing)}")
+    extra = [c for c in cfg.columns if c not in header]
+    if extra:
+        raise ConfigError(f"configuration names column(s) not in the table: {', '.join(extra)}")
+
+
+def anonymize(header: Sequence[str], rows: Sequence[Sequence[str]], cfg: Config,
+              *, io: Optional[tuple[str, Optional[str]]] = None) -> Result:
+    """io, when given, is (input_format, output_format or None) and is recorded in the receipt."""
+    header = list(header)
+    _check_columns(header, cfg)
+    n = len(rows)
+    if n == 0:
+        return _refuse("no_records", n, cfg, io)
+    if n > cfg.max_rows:
+        return _refuse("resource_limit_rows", n, cfg, io)
+
+    pos = {name: i for i, name in enumerate(header)}
+    qi_cols = [h for h in header if cfg.columns[h].role is Role.QI]
+    sens_cols = [h for h in header if cfg.columns[h].role is Role.SENSITIVE]
+
+    # --- generalization tables ---------------------------------------------------------
+    gens: list[Generalizer] = []
+    values: list[list[str]] = []
+    codes: list[list[list[int]]] = []
+    cards: list[list[int]] = []
+    for c in qi_cols:
+        col = [_norm(r[pos[c]]) for r in rows]
+        distinct = list(dict.fromkeys(col))
+        g = make_generalizer(cfg.columns[c].gen or {})
+        g.prepare(distinct)
+        per_level, per_card = [], []
+        for lvl in range(g.levels + 1):
+            ids: dict[str, int] = {}
+            of_value = {v: ids.setdefault(g.label(v, lvl), len(ids)) for v in distinct}
+            per_level.append([of_value[v] for v in col])
+            per_card.append(len(ids))
+        gens.append(g); values.append(col); codes.append(per_level); cards.append(per_card)
+
+    sens_codes: list[list[int]] = []
+    for c in sens_cols:
+        ids2: dict[str, int] = {}
+        sens_codes.append([ids2.setdefault(_norm(r[pos[c]]), len(ids2)) for r in rows])
+
+    # --- search ------------------------------------------------------------------------
+    budget = min(n - 1, int(math.floor(cfg.max_suppression * n)))
+    searcher = Searcher(codes, cards, sens_codes, n, cfg.k, cfg.l, budget, cfg.max_evals)
+    try:
+        found = searcher.run()
+    except Infeasible:
+        return _refuse("infeasible", n, cfg, io)
+    except SearchLimitExceeded:
+        return _refuse("resource_limit_search", n, cfg, io)
+
+    # --- build the output table --------------------------------------------------------
+    dropped = set(found.suppressed)
+    chosen = dict(zip(qi_cols, found.levels))
+    qi_labels = {}
+    for c, g, col in zip(qi_cols, gens, values):
+        lvl = chosen[c]
+        qi_labels[c] = {v: g.label(v, lvl) for v in dict.fromkeys(col)}
+    qi_index = {c: i for i, c in enumerate(qi_cols)}
+
+    out_header = [h for h in header
+                  if cfg.columns[h].role not in (Role.DROP,)
+                  and not (cfg.columns[h].role is Role.ID and cfg.columns[h].action == "drop")]
+    out_rows: list[list[str]] = []
+    for ri, r in enumerate(rows):
+        if ri in dropped:
+            continue
+        out = []
+        for h in out_header:
+            spec = cfg.columns[h]
+            if spec.role is Role.QI:
+                out.append(qi_labels[h][values[qi_index[h]][ri]])
+            elif spec.role is Role.ID:
+                out.append(pseudonym(cfg.key, h, r[pos[h]]))
+            else:
+                out.append(r[pos[h]])
+        out_rows.append(out)
+
+    if cfg.shuffle:
+        SplitMix64(cfg.shuffle_seed).shuffle(out_rows)
+
+    # --- verify on the output itself ---------------------------------------------------
+    m = measure(out_header, out_rows, qi_cols, sens_cols)
+    if m["k"] < cfg.k or any(v < cfg.l for v in m["diversity"].values()) or m["records"] == 0:
+        return _refuse("verification_failed", n, cfg, io)
+
+    # --- receipt -----------------------------------------------------------------------
+    before = measure(header, rows, qi_cols, [])
+    tops = searcher.tops
+    out_pos = {h: i for i, h in enumerate(out_header)}
+    cols_report = []
+    for h in header:
+        spec = cfg.columns[h]
+        entry = {"name": h, "role": spec.role.value}
+        if spec.role is Role.ID:
+            entry["action"] = spec.action
+        elif spec.role is Role.QI:
+            g, lvl = gens[qi_index[h]], chosen[h]
+            entry.update(level=lvl, top_level=g.levels,
+                         description_en=g.describe(lvl, "en"), description_ja=g.describe(lvl, "ja"))
+        elif spec.role is Role.KEEP:
+            col_vals = [r[out_pos[h]] for r in out_rows]
+            entry["unique_ratio"] = round(len(set(col_vals)) / len(col_vals), 4) if col_vals else 0.0
+        cols_report.append(entry)
+
+    d = base("anonymized")
+    d["input"] = {"records": n, "columns": len(header)}
+    d["settings"] = {"k": cfg.k, "l": cfg.l, "max_suppression": cfg.max_suppression}
+    d["result"] = {"records_out": len(out_rows), "suppressed": len(dropped),
+                   "suppression_rate": len(dropped) / n}
+    d["privacy"] = {
+        "quasi_identifiers": qi_cols,
+        "k_requested": cfg.k, "k_achieved": m["k"], "crowds": m["crowds"],
+        "smallest_crowds": m["smallest_crowds"], "records_alone_in_crowd": m["records_in_crowd_of_1"],
+        "max_risk": m["max_risk"], "average_risk": m["average_risk"],
+        "l_requested": cfg.l, "diversity": m["diversity"],
+        "before": {"records_alone": before["records_in_crowd_of_1"],
+                   "records_alone_ratio": before["records_in_crowd_of_1"] / n,
+                   "smallest_crowd": before["k"]},
+    }
+    d["information_loss"] = {"height": sum(found.levels), "max_height": sum(tops),
+                             "precision_loss": float(searcher.loss(found.levels) / len(tops))}
+    d["columns"] = cols_report
+    d["order"] = {"shuffled": cfg.shuffle, "seed": cfg.shuffle_seed if cfg.shuffle else None}
+    d["relaxations"] = [] if cfg.shuffle else ["keep_order"]
+    d["search"] = {"evaluations": found.evaluations, "refinement_truncated": found.truncated}
+    d["verification"] = "passed"
+    _add_io(d, io)
+    return Result("anonymized", out_header, out_rows, Report(d))
+
+
+_DATE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+
+
+def inspect_table(header: Sequence[str], rows: Sequence[Sequence[str]]) -> list[dict]:
+    """Observations per column (no roles are guessed)."""
+    n = len(rows)
+    out = []
+    for i, h in enumerate(header):
+        col = [r[i].strip() for r in rows]
+        nonempty = [v for v in col if v != ""]
+        if nonempty and all(re.match(r"^[+-]?\d+$", v) for v in nonempty):
+            shape = "integer"
+        elif nonempty and all(_DATE.match(v) for v in nonempty):
+            shape = "date"
+        else:
+            shape = "text"
+        out.append({"name": h, "distinct": len(set(col)), "empty": len(col) - len(nonempty),
+                    "unique_ratio": round(len(set(col)) / n, 4) if n else 0.0, "shape": shape})
+    return out