fakesmith 0.1.0__py3-none-any.whl

fakesmith/__init__.py

@@ -0,0 +1,16 @@
+from .smith import FakeSmith
+from .schema import SchemaField, FieldType
+from .detector import infer_schema
+from .sanitizer import sanitize_text, SanitizeResult
+from .result import GenerationResult, FieldSummary
+
+__all__ = [
+    "FakeSmith",
+    "SchemaField",
+    "FieldType",
+    "infer_schema",
+    "sanitize_text",
+    "SanitizeResult",
+    "GenerationResult",
+    "FieldSummary",
+]

fakesmith/cli.py

@@ -0,0 +1,150 @@
+"""
+cli.py — Command-line interface for FakeSmith.
+
+Usage:
+    # Generate fake records from a sample file
+    fakesmith generate --file data.json --count 20 --format csv
+    fakesmith generate --file data.json --count 5  --seed 42 --format sql --table users
+    fakesmith generate --file .env      --count 1  --format env
+
+    # Sanitize raw text in-place (plain text / log lines / config blocks)
+    fakesmith sanitize --text "email is john@co.com and key is sk-abc123"
+    fakesmith sanitize --file raw_log.txt --out clean_log.txt
+
+    # Inspect detected schema
+    fakesmith describe --file data.json
+"""
+
+import argparse
+import sys
+import json
+from pathlib import Path
+
+from .smith import FakeSmith
+from .sanitizer import sanitize_text
+
+
+def detect_source_type(path: str) -> str:
+    ext = Path(path).suffix.lower()
+    return {".json": "json", ".csv": "csv"}.get(ext, "auto")
+
+
+def cmd_generate(args):
+    try:
+        with open(args.file) as f:
+            raw = f.read()
+    except FileNotFoundError:
+        print(f"❌ File not found: {args.file}", file=sys.stderr)
+        sys.exit(1)
+
+    smith = FakeSmith.from_sample(raw, source_type=detect_source_type(args.file))
+
+    result = smith.generate(args.count, seed=args.seed)
+
+    if args.summary:
+        result.print_summary()
+
+    if args.format == "json":
+        output = json.dumps(result.records, indent=2, default=str)
+    elif args.format == "csv":
+        output = smith.to_csv(args.count, seed=args.seed)
+    elif args.format == "sql":
+        output = smith.to_sql(args.count, table_name=args.table, seed=args.seed)
+    elif args.format == "env":
+        output = smith.to_env(seed=args.seed)
+
+    if args.out:
+        with open(args.out, "w") as f:
+            f.write(output)
+        print(f"✅ Saved {args.count} records → {args.out}")
+    else:
+        print(output)
+
+
+def cmd_sanitize(args):
+    if args.text:
+        raw = args.text
+    elif args.file:
+        try:
+            with open(args.file) as f:
+                raw = f.read()
+        except FileNotFoundError:
+            print(f"❌ File not found: {args.file}", file=sys.stderr)
+            sys.exit(1)
+    else:
+        print("❌ Provide --text or --file", file=sys.stderr)
+        sys.exit(1)
+
+    result = sanitize_text(raw, seed=args.seed)
+
+    if args.summary or args.file:
+        result.print_summary()
+
+    if args.out:
+        with open(args.out, "w") as f:
+            f.write(result.sanitized)
+        print(f"✅ Sanitized output saved → {args.out}")
+    else:
+        print(result.sanitized)
+
+
+def cmd_describe(args):
+    try:
+        with open(args.file) as f:
+            raw = f.read()
+    except FileNotFoundError:
+        print(f"❌ File not found: {args.file}", file=sys.stderr)
+        sys.exit(1)
+
+    smith = FakeSmith.from_sample(raw, source_type=detect_source_type(args.file))
+    smith.describe()
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="fakesmith",
+        description="Generate or sanitize fake data safe to share with LLMs.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    # ── generate ──────────────────────────────────────────────────────────────
+    gen = sub.add_parser("generate", aliases=["gen", "g"],
+                         help="Generate fake records from a sample file")
+    gen.add_argument("--file",    "-f", required=True)
+    gen.add_argument("--count",   "-n", type=int, default=10)
+    gen.add_argument("--seed",    "-s", type=int, default=None,
+                     help="Integer seed for deterministic output")
+    gen.add_argument("--format",  "-o", default="json",
+                     choices=["json", "csv", "sql", "env"])
+    gen.add_argument("--table",   "-t", default="records")
+    gen.add_argument("--out",           default=None)
+    gen.add_argument("--summary",       action="store_true",
+                     help="Print change summary and warnings")
+
+    # ── sanitize ──────────────────────────────────────────────────────────────
+    san = sub.add_parser("sanitize", aliases=["san", "s"],
+                         help="Replace secrets/PII in raw text in-place")
+    san_src = san.add_mutually_exclusive_group(required=True)
+    san_src.add_argument("--text", "-t", help="Inline string to sanitize")
+    san_src.add_argument("--file", "-f", help="File to sanitize")
+    san.add_argument("--out",      "-o", default=None, help="Output file")
+    san.add_argument("--seed",     "-s", type=int, default=None)
+    san.add_argument("--summary",        action="store_true")
+
+    # ── describe ──────────────────────────────────────────────────────────────
+    desc = sub.add_parser("describe", aliases=["d"],
+                          help="Show detected schema and sensitivity flags")
+    desc.add_argument("--file", "-f", required=True)
+
+    args = parser.parse_args()
+
+    if args.command in ("generate", "gen", "g"):
+        cmd_generate(args)
+    elif args.command in ("sanitize", "san", "s"):
+        cmd_sanitize(args)
+    elif args.command in ("describe", "d"):
+        cmd_describe(args)
+
+
+if __name__ == "__main__":
+    main()

fakesmith/detector.py

@@ -0,0 +1,217 @@
+"""
+detector.py — Infer a FakeSmith schema from sample JSON, CSV, or a Python dict.
+"""
+
+import re
+import json
+import csv
+import io
+from typing import Union
+from .schema import SchemaField, FieldType
+
+
+# Regex heuristics for common patterns
+
+PATTERNS = [
+    (FieldType.UUID,          r'^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'),
+    (FieldType.EMAIL,         r'^[\w\.-]+@[\w\.-]+\.\w+$'),
+    (FieldType.PHONE,         r'^[\+\d][\d\s\-\(\)\.]{6,20}$'),
+    (FieldType.IP_ADDRESS,    r'^\d{1,3}(\.\d{1,3}){3}$'),
+    (FieldType.IPV6,          r'^([0-9a-f]{1,4}:){7}[0-9a-f]{1,4}$'),
+    (FieldType.MAC_ADDRESS,   r'^([0-9a-f]{2}[:\-]){5}[0-9a-f]{2}$'),
+    (FieldType.URL,           r'^https?://'),
+    (FieldType.DATETIME,      r'^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}'),
+    (FieldType.DATE,          r'^\d{4}-\d{2}-\d{2}$'),
+    (FieldType.TIME,          r'^\d{2}:\d{2}(:\d{2})?$'),
+    (FieldType.JWT_TOKEN,     r'^eyJ[A-Za-z0-9\-_]+\.[A-Za-z0-9\-_]+\.[A-Za-z0-9\-_]+$'),
+    (FieldType.CARD_NUMBER,   r'^\d{4}[\s\-]?\d{4}[\s\-]?\d{4}[\s\-]?\d{4}$'),
+    (FieldType.IBAN,          r'^[A-Z]{2}\d{2}[A-Z0-9]{1,30}$'),
+    (FieldType.PASSWORD_HASH, r'^(\$2[aby]\$|sha256\$|[0-9a-f]{32,128})'),
+    (FieldType.API_KEY,       r'^(sk-|pk-|api-|key-|Bearer )[A-Za-z0-9\-_]{8,}'),
+    (FieldType.SLUG,          r'^[a-z0-9]+(-[a-z0-9]+)*$'),
+]
+
+# Name-based heuristics (field name keywords → type)
+NAME_HINTS = {
+    FieldType.UUID:         ['id', 'uuid', 'guid'],
+    FieldType.EMAIL:        ['email', 'mail'],
+    FieldType.PHONE:        ['phone', 'mobile', 'tel', 'fax'],
+    FieldType.FULL_NAME:    ['full_name', 'fullname', 'name'],
+    FieldType.FIRST_NAME:   ['first_name', 'firstname', 'fname'],
+    FieldType.LAST_NAME:    ['last_name', 'lastname', 'lname', 'surname'],
+    FieldType.USERNAME:     ['username', 'user_name', 'handle', 'login'],
+    FieldType.PASSWORD:     ['password', 'passwd', 'pwd'],
+    FieldType.PASSWORD_HASH:['password_hash', 'hashed_password', 'pwd_hash'],
+    FieldType.API_KEY:      ['api_key', 'apikey', 'api_token', 'access_key'],
+    FieldType.SECRET_TOKEN: ['secret', 'token', 'refresh_token', 'auth_token'],
+    FieldType.JWT_TOKEN:    ['jwt', 'id_token', 'bearer'],
+    FieldType.ADDRESS:      ['address', 'street', 'addr'],
+    FieldType.CITY:         ['city', 'town'],
+    FieldType.STATE:        ['state', 'province', 'region'],
+    FieldType.COUNTRY:      ['country', 'nation'],
+    FieldType.ZIP_CODE:     ['zip', 'postal', 'postcode', 'zip_code'],
+    FieldType.LATITUDE:     ['lat', 'latitude'],
+    FieldType.LONGITUDE:    ['lon', 'lng', 'longitude'],
+    FieldType.AMOUNT:       ['amount', 'price', 'cost', 'fee', 'total', 'balance', 'salary'],
+    FieldType.CURRENCY:     ['currency', 'currency_code'],
+    FieldType.CARD_NUMBER:  ['card_number', 'card_num', 'pan'],
+    FieldType.CARD_EXPIRY:  ['expiry', 'expiration', 'exp_date'],
+    FieldType.BANK_ACCOUNT: ['account', 'account_number', 'bban'],
+    FieldType.IBAN:         ['iban'],
+    FieldType.COMPANY:      ['company', 'organization', 'employer', 'firm'],
+    FieldType.JOB_TITLE:    ['job', 'title', 'position', 'role', 'occupation'],
+    FieldType.DEPARTMENT:   ['department', 'dept', 'division', 'team'],
+    FieldType.DATETIME:     ['created_at', 'updated_at', 'deleted_at', 'datetime', 'timestamp'],
+    FieldType.DATE:         ['date', 'day'],
+    FieldType.DATE_OF_BIRTH:['dob', 'birth_date', 'birthdate', 'date_of_birth'],
+    FieldType.IP_ADDRESS:   ['ip', 'ip_address', 'ipv4'],
+    FieldType.USER_AGENT:   ['user_agent', 'useragent', 'browser'],
+    FieldType.URL:          ['url', 'link', 'href', 'website', 'homepage'],
+    FieldType.STATUS:       ['status', 'state', 'stage'],
+    FieldType.DESCRIPTION:  ['description', 'desc', 'details', 'bio', 'summary', 'about'],
+    FieldType.TITLE:        ['title', 'heading', 'subject'],
+    FieldType.TAG:          ['tag', 'label', 'category', 'type'],
+    FieldType.GENDER:       ['gender', 'sex'],
+    FieldType.PERCENTAGE:   ['percent', 'percentage', 'rate', 'ratio'],
+    FieldType.BOOLEAN:      ['is_', 'has_', 'can_', 'active', 'enabled', 'verified'],
+}
+
+
+def _detect_from_name(field_name: str) -> FieldType:
+    """Guess field type purely from its name."""
+    lower = field_name.lower()
+    for ftype, keywords in NAME_HINTS.items():
+        for kw in keywords:
+            if kw in lower:
+                return ftype
+    return None
+
+
+def _detect_from_value(value) -> FieldType:
+    """Guess field type from a sample value."""
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return FieldType.BOOLEAN
+    if isinstance(value, int):
+        return FieldType.INTEGER
+    if isinstance(value, float):
+        return FieldType.FLOAT
+    if isinstance(value, str):
+        for ftype, pattern in PATTERNS:
+            if re.match(pattern, value.strip(), re.IGNORECASE):
+                return ftype
+    return None
+
+
+# Name hints for security-sensitive fields always win over value detection.
+_NAME_PRIORITY_TYPES = {
+    FieldType.PASSWORD, FieldType.PASSWORD_HASH, FieldType.API_KEY,
+    FieldType.SECRET_TOKEN, FieldType.JWT_TOKEN, FieldType.CARD_NUMBER,
+    FieldType.CARD_EXPIRY, FieldType.BANK_ACCOUNT, FieldType.IBAN,
+    FieldType.DATE_OF_BIRTH,
+}
+
+
+def _detect_field(field_name: str, sample_value=None) -> FieldType:
+    """Combine name + value heuristics.
+
+    Priority:
+      1. Name hint for security-sensitive types (password, api_key, etc.)
+      2. Value-based regex for precise structural matches (email, UUID, IP…)
+      3. Name hint for non-sensitive types
+      4. Generic value type (int, float, bool)
+      5. SENTENCE fallback
+    """
+    by_name  = _detect_from_name(field_name)
+    by_value = _detect_from_value(sample_value) if sample_value is not None else None
+
+    # Security-sensitive name hints always win — prevents "s3cr3t" → SLUG
+    if by_name and by_name in _NAME_PRIORITY_TYPES:
+        return by_name
+
+    # Value regex is precise for structural types
+    if by_value and by_value not in (FieldType.INTEGER, FieldType.FLOAT,
+                                     FieldType.BOOLEAN, FieldType.SLUG):
+        return by_value
+
+    if by_name:
+        return by_name
+    if by_value:
+        return by_value
+
+    # Python type fallbacks
+    if isinstance(sample_value, bool):   return FieldType.BOOLEAN
+    if isinstance(sample_value, int):    return FieldType.INTEGER
+    if isinstance(sample_value, float):  return FieldType.FLOAT
+
+    return FieldType.SENTENCE
+
+
+def infer_schema(source: Union[str, dict, list], source_type: str = "auto") -> list[SchemaField]:
+    """
+    Infer a list of SchemaFields from sample data.
+
+    Args:
+        source:      A JSON string, CSV string, Python dict, or list of dicts.
+        source_type: "json" | "csv" | "dict" | "auto" (default)
+
+    Returns:
+        List of SchemaField objects ready to pass into FakeSmith.
+    """
+    record = _extract_sample_record(source, source_type)
+    fields = []
+    for key, value in record.items():
+        detected = _detect_field(key, value)
+        nullable = value is None
+        fields.append(SchemaField(name=key, field_type=detected, nullable=nullable))
+    return fields
+
+
+def _extract_sample_record(source, source_type) -> dict:
+    """Pull the first record out of whatever format was given."""
+    if isinstance(source, dict):
+        return source
+    if isinstance(source, list) and source:
+        return source[0]
+
+    if source_type == "auto":
+        stripped = source.strip() if isinstance(source, str) else ""
+        if stripped.startswith(("{", "[")):
+            source_type = "json"
+        else:
+            source_type = "csv"
+
+    if source_type == "json":
+        data = json.loads(source)
+        return data[0] if isinstance(data, list) else data
+
+    if source_type == "csv":
+        reader = csv.DictReader(io.StringIO(source))
+        for row in reader:
+            return dict(row)
+
+    raise ValueError(f"Cannot parse source with source_type='{source_type}'")
+
+
+# Gap 5: Sensitive field registry
+# Used by smith.py to flag fields that contain real PII or secrets.
+
+SENSITIVE_TYPES = {
+    FieldType.EMAIL,
+    FieldType.PHONE,
+    FieldType.PASSWORD,
+    FieldType.PASSWORD_HASH,
+    FieldType.CARD_NUMBER,
+    FieldType.CARD_EXPIRY,
+    FieldType.CARD_CVV,
+    FieldType.BANK_ACCOUNT,
+    FieldType.IBAN,
+    FieldType.API_KEY,
+    FieldType.SECRET_TOKEN,
+    FieldType.JWT_TOKEN,
+    FieldType.DATE_OF_BIRTH,
+    FieldType.IP_ADDRESS,
+    FieldType.IPV6,
+    FieldType.MAC_ADDRESS,
+}

fakesmith/generators.py

@@ -0,0 +1,205 @@
+"""
+generators.py — Maps every FieldType to a Faker-backed callable.
+Includes format-preserving helpers (Gap 4) and seed threading (Gap 1).
+"""
+
+import re
+import random
+import uuid
+import base64
+import hashlib
+import time
+from typing import Union, Optional
+from faker import Faker
+from .schema import SchemaField, FieldType
+
+_fakers: dict[str, Faker] = {}
+
+
+def seed_all(seed: int) -> None:
+    """Seed Python random AND every Faker instance for deterministic output."""
+    random.seed(seed)
+    Faker.seed(seed)
+    for f in _fakers.values():
+        f.seed_instance(seed)
+
+
+def _get_faker(locale: str = "en_US") -> Faker:
+    if locale not in _fakers:
+        _fakers[locale] = Faker(locale)
+    return _fakers[locale]
+
+
+# Gap 4: format-preserving helpers 
+
+def _preserve_phone(original: str) -> str:
+    """Return a fake phone that mirrors the separator + prefix style of original."""
+    has_plus   = original.strip().startswith('+')
+    has_parens = '(' in original
+    sep        = '-' if '-' in original else (' ' if ' ' in original else '')
+    digits     = re.sub(r'\D', '', original)
+    fake_d     = ''.join(str(random.randint(0, 9)) for _ in digits)
+    if has_plus and len(digits) > 10:
+        cc   = fake_d[:len(digits) - 10]
+        rest = fake_d[len(digits) - 10:]
+        if has_parens:
+            return f"+{cc}{sep}({rest[:3]}){sep}{rest[3:6]}{sep}{rest[6:]}"
+        return f"+{cc}{sep}{rest[:3]}{sep}{rest[3:6]}{sep}{rest[6:]}"
+    if has_parens:
+        return f"({fake_d[:3]}){sep}{fake_d[3:6]}{sep}{fake_d[6:]}"
+    if sep:
+        return f"{fake_d[:3]}{sep}{fake_d[3:6]}{sep}{fake_d[6:]}"
+    return fake_d
+
+
+def _preserve_api_key(original: str, prefix: Optional[str] = None) -> str:
+    """Return a fake key with the same prefix and character count."""
+    if prefix:
+        length = max(len(original) - len(prefix), 16)
+        chars  = 'abcdefghijklmnopqrstuvwxyz0123456789'
+        return prefix + ''.join(random.choices(chars, k=length))
+    m = re.match(r'^([a-zA-Z0-9_\-]{2,8}[-_])', original)
+    detected = m.group(1) if m else 'key-'
+    length   = max(len(original) - len(detected), 16)
+    chars    = 'abcdefghijklmnopqrstuvwxyz0123456789'
+    return detected + ''.join(random.choices(chars, k=length))
+
+
+def _preserve_card(original: str) -> str:
+    """Return a fake card that mirrors the spacing/dash format of original."""
+    sep  = '-' if '-' in original else (' ' if ' ' in original else '')
+    fake = Faker().credit_card_number()
+    if sep and len(original.replace(sep, '')) == 16:
+        return sep.join([fake[i:i+4] for i in range(0, 16, 4)])
+    return fake
+
+
+def _fake_jwt() -> str:
+    """Generate a structurally valid but fake JWT token."""
+    def b64(data: str) -> str:
+        return base64.urlsafe_b64encode(data.encode()).rstrip(b"=").decode()
+    header  = b64('{"alg":"HS256","typ":"JWT"}')
+    payload = b64(f'{{"sub":"{uuid.uuid4()}","iat":{int(time.time())}}}')
+    sig     = base64.urlsafe_b64encode(uuid.uuid4().bytes).rstrip(b"=").decode()
+    return f"{header}.{payload}.{sig}"
+
+
+def _fake_api_key(prefix: str = "sk-") -> str:
+    fake = _get_faker()
+    return prefix + fake.lexify("?" * 32, letters="abcdefghijklmnopqrstuvwxyz0123456789")
+
+
+def _fake_secret_token() -> str:
+    return hashlib.sha256(uuid.uuid4().bytes).hexdigest()
+
+
+def generate_value(field: SchemaField, original_value: Optional[str] = None) -> any:
+    """Generate a single fake value. original_value enables format-preserving output."""
+    fake = _get_faker(field.locale or "en_US")
+
+    # Handle nullable fields
+    if field.nullable and random.random() < field.null_probability:
+        return None
+
+    # Custom generator takes full priority
+    if field.field_type == FieldType.CUSTOM:
+        return field.generator()
+
+    # Choices-based field
+    if field.choices:
+        return random.choice(field.choices)
+
+    ft = field.field_type
+
+    # Identity
+    if ft == FieldType.UUID:          return fake.uuid4()
+    if ft == FieldType.FULL_NAME:     return fake.name()
+    if ft == FieldType.FIRST_NAME:    return fake.first_name()
+    if ft == FieldType.LAST_NAME:     return fake.last_name()
+    if ft == FieldType.USERNAME:      return fake.user_name()
+    if ft == FieldType.EMAIL:         return fake.email()
+    if ft == FieldType.PHONE:
+        if original_value and isinstance(original_value, str):
+            return _preserve_phone(original_value)
+        return fake.phone_number()
+    if ft == FieldType.PASSWORD:      return fake.password(length=12)
+    if ft == FieldType.PASSWORD_HASH: return hashlib.sha256(fake.password().encode()).hexdigest()
+
+    # ── Location 
+    if ft == FieldType.ADDRESS:       return fake.address()
+    if ft == FieldType.CITY:          return fake.city()
+    if ft == FieldType.STATE:         return fake.state() if hasattr(fake, "state") else fake.city()
+    if ft == FieldType.COUNTRY:       return fake.country()
+    if ft == FieldType.ZIP_CODE:      return fake.postcode()
+    if ft == FieldType.LATITUDE:      return float(fake.latitude())
+    if ft == FieldType.LONGITUDE:     return float(fake.longitude())
+
+    # ── Finance ─
+    if ft == FieldType.CARD_NUMBER:
+        if original_value and isinstance(original_value, str):
+            return _preserve_card(original_value)
+        return fake.credit_card_number()
+    if ft == FieldType.CARD_EXPIRY:   return fake.credit_card_expire()
+    if ft == FieldType.CARD_CVV:      return fake.credit_card_security_code()
+    if ft == FieldType.BANK_ACCOUNT:  return fake.bban()
+    if ft == FieldType.IBAN:          return fake.iban()
+    if ft == FieldType.CURRENCY:      return random.choice(["USD", "EUR", "GBP", "GHS", "NGN", "JPY", "CAD"])
+    if ft == FieldType.AMOUNT:
+        lo = field.min_value if field.min_value is not None else 1.0
+        hi = field.max_value if field.max_value is not None else 99999.0
+        return round(random.uniform(lo, hi), 2)
+
+    # Business
+    if ft == FieldType.COMPANY:       return fake.company()
+    if ft == FieldType.JOB_TITLE:     return fake.job()
+    if ft == FieldType.DEPARTMENT:    return random.choice(["Engineering", "Marketing", "Finance", "HR", "Sales", "Design", "Operations"])
+    if ft == FieldType.API_KEY:
+        if original_value and isinstance(original_value, str):
+            return _preserve_api_key(original_value, field.prefix)
+        return _fake_api_key(field.prefix or "sk-")
+    if ft == FieldType.SECRET_TOKEN:  return _fake_secret_token()
+    if ft == FieldType.JWT_TOKEN:     return _fake_jwt()
+    if ft == FieldType.WEBHOOK_URL:   return f"https://hooks.{fake.domain_name()}/webhook/{uuid.uuid4().hex[:8]}"
+
+    # Dates & Times
+    if ft == FieldType.DATETIME:      return fake.date_time_this_year().isoformat()
+    if ft == FieldType.DATE:          return fake.date_this_year().isoformat()
+    if ft == FieldType.TIME:          return fake.time()
+    if ft == FieldType.DATE_OF_BIRTH: return fake.date_of_birth(minimum_age=18, maximum_age=70).isoformat()
+    if ft == FieldType.TIMESTAMP:     return int(fake.date_time_this_year().timestamp())
+
+    # Web & Tech
+    if ft == FieldType.IP_ADDRESS:    return fake.ipv4()
+    if ft == FieldType.IPV6:          return fake.ipv6()
+    if ft == FieldType.MAC_ADDRESS:   return fake.mac_address()
+    if ft == FieldType.USER_AGENT:    return fake.user_agent()
+    if ft == FieldType.URL:           return fake.url()
+    if ft == FieldType.DOMAIN:        return fake.domain_name()
+    if ft == FieldType.SLUG:          return fake.slug()
+
+    # Content
+    if ft == FieldType.WORD:          return fake.word()
+    if ft == FieldType.SENTENCE:      return fake.sentence()
+    if ft == FieldType.PARAGRAPH:     return fake.paragraph()
+    if ft == FieldType.TITLE:         return fake.catch_phrase()
+    if ft == FieldType.DESCRIPTION:   return fake.text(max_nb_chars=200)
+    if ft == FieldType.TAG:           return fake.word()
+
+    # Numeric
+    if ft == FieldType.INTEGER:
+        lo = int(field.min_value) if field.min_value is not None else 0
+        hi = int(field.max_value) if field.max_value is not None else 10000
+        return random.randint(lo, hi)
+    if ft == FieldType.FLOAT:
+        lo = field.min_value if field.min_value is not None else 0.0
+        hi = field.max_value if field.max_value is not None else 1000.0
+        return round(random.uniform(lo, hi), 4)
+    if ft == FieldType.BOOLEAN:       return random.choice([True, False])
+    if ft == FieldType.PERCENTAGE:    return round(random.uniform(0, 100), 2)
+
+    # Enums
+    if ft == FieldType.STATUS:        return random.choice(["active", "inactive", "pending", "suspended", "archived"])
+    if ft == FieldType.GENDER:        return random.choice(["male", "female", "non-binary", "prefer_not_to_say"])
+
+    # Fallback
+    return fake.word()

fakesmith/result.py

@@ -0,0 +1,75 @@
+"""
+result.py — GenerationResult wraps generated records with a change summary
+and any warnings raised during detection.
+"""
+
+from dataclasses import dataclass, field
+from typing import List, Dict, Optional
+
+
+@dataclass
+class FieldSummary:
+    """What happened to one field."""
+    name: str
+    detected_type: str
+    is_sensitive: bool
+    original_sample: str   # first value from source (truncated / redacted)
+    note: str = ""
+
+
+@dataclass
+class GenerationResult:
+    """
+    Returned by FakeSmith.generate() and all to_*() methods when
+    return_summary=True is passed (or always from generate_with_summary()).
+
+    Attributes:
+        records:   The generated fake records.
+        summary:   Per-field breakdown of what was detected and replaced.
+        warnings:  Human-readable warnings for sensitive fields found.
+        seed:      The seed used, if any (None = random).
+    """
+    records: List[Dict]
+    summary: List[FieldSummary] = field(default_factory=list)
+    warnings: List[str] = field(default_factory=list)
+    seed: Optional[int] = None
+
+    # ── Display ───────────────────────────────────────────────────────────────
+
+    def print_summary(self) -> None:
+        """Print a human-readable change report to stdout."""
+        print(f"\n{'─'*62}")
+        print(f"  FakeSmith — change summary  ({len(self.records)} records generated)")
+        if self.seed is not None:
+            print(f"  Seed: {self.seed}  (re-run with --seed {self.seed} for identical output)")
+        print(f"{'─'*62}")
+        print(f"  {'Field':<22} {'Detected type':<20} {'Sensitive'}")
+        print(f"  {'─'*20} {'─'*18} {'─'*9}")
+        for fs in self.summary:
+            flag = "  *** YES ***" if fs.is_sensitive else "  no"
+            print(f"  {fs.name:<22} {fs.detected_type:<20}{flag}")
+            if fs.note:
+                print(f"  {'':22} {fs.note}")
+        print(f"{'─'*62}")
+        if self.warnings:
+            print()
+            for w in self.warnings:
+                print(f"  [WARNING] {w}")
+            print()
+
+    def to_dict(self) -> dict:
+        """Machine-readable summary dict."""
+        return {
+            "seed": self.seed,
+            "records_generated": len(self.records),
+            "fields": [
+                {
+                    "name": fs.name,
+                    "detected_type": fs.detected_type,
+                    "sensitive": fs.is_sensitive,
+                    "note": fs.note,
+                }
+                for fs in self.summary
+            ],
+            "warnings": self.warnings,
+        }