{
  "markdown": "> **Moved.** This repo has moved into the [`benzsevern/goldenmatch`](https://github.com/benzsevern/goldenmatch) monorepo at `packages/python/goldenflow (and packages/typescript/goldenflow)/`. This repo is archived; new development happens in the monorepo.\n\n<!-- mcp-name: io.github.benzsevern/goldenflow -->\n# GoldenFlow\n\n**Data transformation toolkit — standardize, reshape, and normalize messy data before it hits your pipeline.**\nBuilt by [Ben Severn](https://bensevern.dev).\n\nWorks on files (CSV, Excel, Parquet), cloud storage (S3, GCS), or live databases. Zero-config mode auto-detects what needs fixing. One command to clean what GoldenCheck found and prep what GoldenMatch needs. **Available in Python and TypeScript** with full feature parity.\n\n[![PyPI](https://img.shields.io/pypi/v/goldenflow?color=d4a017)](https://pypi.org/project/goldenflow/)\n[![npm](https://img.shields.io/npm/v/goldenflow?color=d4a017)](https://www.npmjs.com/package/goldenflow)\n[![CI](https://github.com/benzsevern/goldenflow/actions/workflows/test.yml/badge.svg)](https://github.com/benzsevern/goldenflow/actions/workflows/test.yml)\n[![codecov](https://codecov.io/gh/benzsevern/goldenflow/graph/badge.svg)](https://codecov.io/gh/benzsevern/goldenflow)\n[![Downloads](https://static.pepy.tech/badge/goldenflow/month)](https://pepy.tech/project/goldenflow)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://python.org)\n[![Node 20+](https://img.shields.io/badge/node-20%2B-339933)](https://nodejs.org)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n[![Docs](https://img.shields.io/badge/docs-benzsevern.github.io%2Fgoldenflow-d4a017)](https://benzsevern.github.io/goldenflow/)\n[![DQBench](https://img.shields.io/badge/DQBench-100%2F100-gold)](https://github.com/benzsevern/dqbench)\n[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/benzsevern/goldenflow/blob/main/scripts/goldenflow_demo.ipynb)\n\n```bash\n# Python\npip install goldenflow\ngoldenflow transform data.csv\n\n# TypeScript / Node.js\nnpm install goldenflow\nnpx goldenflow-js transform data.csv\n```\n\n---\n\n## The Problem\n\nYour data arrives broken in predictable ways:\n\n- Phone numbers come in 15 different formats\n- Dates are mixed between MM/DD/YYYY and YYYY-MM-DD\n- Addresses have inconsistent abbreviations\n- Column names don't match between systems (\"fname\" vs \"first_name\" vs \"given_name\")\n- Values have leading whitespace, unicode garbage, smart quotes\n- Categoricals are inconsistent (\"USA\", \"US\", \"United States\")\n\nEvery data engineer writes throwaway scripts to fix these. Every script is slightly different. None of them are reusable.\n\nGoldenFlow makes the transforms reusable, composable, and automatic.\n\n---\n\n## Quick Start\n\n### Python\n\n```bash\npip install goldenflow\n\n# Auto-transform (zero-config)\ngoldenflow transform messy_data.csv\n\n# Try the demo first\ngoldenflow demo\ngoldenflow transform demo_data.csv -c demo_config.yaml\n\n# With config\ngoldenflow learn messy_data.csv -o config.yaml\ngoldenflow transform messy_data.csv -c config.yaml\n\n# Schema mapping\ngoldenflow map --source system_a.csv --target system_b.csv\n\n# Full pipeline\ngoldencheck scan data.csv\ngoldenflow transform data.csv\ngoldenmatch dedupe data_transformed.csv\n```\n\n### TypeScript / Node.js\n\n```bash\nnpm install goldenflow\n\n# Auto-transform (zero-config)\nnpx goldenflow-js transform messy_data.csv\n\n# Try the demo first\nnpx goldenflow-js demo\nnpx goldenflow-js transform demo_data.csv -c demo_config.yaml\n\n# With config\nnpx goldenflow-js learn messy_data.csv -o config.yaml\nnpx goldenflow-js transform messy_data.csv -c config.yaml\n\n# Schema mapping\nnpx goldenflow-js map -s system_a.csv -t system_b.csv\n```\n\n### Programmatic (TypeScript)\n\n```typescript\nimport { TransformEngine } from \"goldenflow\";\n\nconst result = new TransformEngine().transformDf([\n  { name: \"  JOHN  \", phone: \"(555) 123-4567\", email: \"John@Example.COM\" },\n]);\nconsole.log(result.rows[0]);\n// { name: \"JOHN\", phone: \"+15551234567\", email: \"john@example.com\" }\n```\n\n---\n\n## Zero-Config Mode\n\n```bash\ngoldenflow transform customers.csv\n# or just:\ngoldenflow customers.csv\n```\n\nGoldenFlow profiles every column and applies safe transforms automatically:\n\n- Strips whitespace and normalizes unicode\n- Standardizes phone numbers to E.164 format\n- Normalizes email casing\n- Parses and standardizes date formats to ISO 8601\n- Normalizes zip codes (zero-padding, strip +4)\n- Replaces smart/curly quotes with straight quotes\n- Auto-corrects categorical misspellings via fuzzy matching\n\nOutput: a clean CSV with a sidecar manifest showing every transform applied.\n\n```\ncustomers.csv           -> customers_transformed.csv\n                        -> customers_manifest.json\n```\n\nThe manifest is an audit trail — what changed, why, and which rows were affected.\n\n---\n\n## CLI Commands\n\nGoldenFlow has 14 commands. The most common ones:\n\n```bash\n# Core transforms\ngoldenflow transform data.csv                    # Zero-config: auto-detect and fix\ngoldenflow transform data.csv -c config.yaml     # Apply saved config\ngoldenflow transform data.csv --domain healthcare # Use a domain pack\ngoldenflow transform data.csv --strict           # Fail on any transform error\ngoldenflow transform data.csv --llm              # Enable LLM-enhanced corrections\ngoldenflow data.csv                              # Shorthand: auto-routes to transform\n\n# Schema & profiling\ngoldenflow map -s a.csv -t b.csv                 # Auto-map schemas between files\ngoldenflow profile data.csv                      # Show column profiles\ngoldenflow learn data.csv -o config.yaml         # Generate config from data patterns\ngoldenflow validate data.csv                     # Dry-run: show what would change\ngoldenflow diff before.csv after.csv             # Compare pre/post transform\n\n# Continuous & scheduled\ngoldenflow watch ./data/                         # Auto-transform new/changed files\ngoldenflow schedule data.csv --every 1h          # Run on a schedule (5m, 1h, 30s...)\ngoldenflow stream large_file.csv --chunk-size 50000  # Stream-process in batches\n\n# Discovery & history\ngoldenflow init data.csv                         # Interactive setup wizard\ngoldenflow demo                                  # Generate sample data to try\ngoldenflow history                               # Show recent transform runs\ngoldenflow history -n 50                         # Last 50 runs\n\n# Integrations\ngoldenflow interactive data.csv                  # Launch TUI\ngoldenflow serve                                 # REST API for real-time transforms\ngoldenflow mcp-serve                             # MCP server for Claude Desktop\n```\n\n### Default Routing\n\nRunning `goldenflow <file>` without a subcommand auto-routes to `transform`:\n\n```bash\ngoldenflow customers.csv       # equivalent to: goldenflow transform customers.csv\ngoldenflow -                   # read from stdin, write to stdout\n```\n\n---\n\n## Streaming\n\nFor files too large to load into memory, use `StreamProcessor` or the `stream` command:\n\n```bash\ngoldenflow stream large_file.csv --chunk-size 50000\n```\n\n```python\nfrom goldenflow.streaming import StreamProcessor\n\nprocessor = StreamProcessor(config=config)\n\n# Process a single record\nresult = processor.transform_one({\"name\": \"  John  \", \"phone\": \"(555) 123-4567\"})\n\n# Process a batch\nresult = processor.transform_batch(df_batch)\n\n# Stream a large file in chunks\nfor result in processor.stream_file(\"large_data.csv\", chunk_size=10_000):\n    write_to_output(result.df)\n\nprint(f\"Processed {processor.batches_processed} batches\")\n```\n\n---\n\n## Cloud Connectors\n\nGoldenFlow reads from and writes to S3 and Google Cloud Storage transparently:\n\n```bash\n# S3\ngoldenflow transform s3://my-bucket/raw/customers.csv -o s3://my-bucket/clean/\n\n# GCS\ngoldenflow transform gs://my-bucket/data/records.csv\n```\n\n```python\nfrom goldenflow.connectors.s3 import read_s3, write_s3\nfrom goldenflow.connectors.gcs import read_gcs, write_gcs\n\ndf = read_s3(\"s3://my-bucket/raw/customers.csv\")\ndf = read_gcs(\"gs://my-bucket/data/records.csv\")\n```\n\nCloud paths are detected automatically — no extra flags needed.\n\n---\n\n## Watch Mode\n\nAuto-transform files as they arrive in a directory:\n\n```bash\ngoldenflow watch ./data/\ngoldenflow watch ./incoming/ -c config.yaml -o ./processed/\n```\n\nGoldenFlow polls the directory and applies transforms to any new or changed files.\n\n---\n\n## Scheduling\n\nRun transforms on a repeating schedule:\n\n```bash\ngoldenflow schedule data.csv --every 1h\ngoldenflow schedule data.csv --every 30m -c config.yaml -o ./output/\n```\n\nSupported intervals: `30s`, `5m`, `1h`, `2h`, etc.\n\n---\n\n## Setup Wizard\n\nGenerate a YAML config interactively:\n\n```bash\ngoldenflow init data.csv\n```\n\nThe wizard profiles your data, suggests transforms, and saves a `goldenflow.yaml` ready to use.\n\n---\n\n## History\n\nGoldenFlow tracks every transform run in `~/.goldenflow/history/`:\n\n```bash\ngoldenflow history         # Last 20 runs\ngoldenflow history -n 50   # Last 50 runs\n```\n\nEach run record captures: source file, row count, transforms applied, errors, and duration.\n\n---\n\n## Schema Mapping\n\nWhen you need to merge data from different systems:\n\n```bash\ngoldenflow map --source crm_export.csv --target warehouse_schema.csv\n```\n\nGoldenFlow auto-maps columns between schemas using name similarity and data profiling:\n\n```\ncrm_export.csv              warehouse schema\n-----                       -----\nemail_address      ->       email (rename)\nphone_number       ->       phone (rename)\nfname              ->       first_name (alias match)\nst                 ->       state (alias match)\n```\n\nAmbiguous mappings get flagged for human review. Confident mappings apply automatically.\n\n---\n\n## Domain Packs\n\nPre-configured transform sets for common industries. All 5 are now implemented:\n\n```bash\ngoldenflow transform patients.csv --domain healthcare\ngoldenflow transform employees.csv --domain people_hr\ngoldenflow transform transactions.csv --domain finance\ngoldenflow transform orders.csv --domain ecommerce\ngoldenflow transform listings.csv --domain real_estate\n```\n\n| Domain Pack | What It Covers |\n|-------------|---------------|\n| **People/HR** | Name parsing, SSN formatting, employment dates, gender/boolean standardization |\n| **Healthcare** | Patient IDs, diagnosis codes, clinical dates, HIPAA-sensitive field handling |\n| **Finance** | Currency normalization, account numbers, transaction dates, amount parsing |\n| **E-commerce** | SKU normalization, price parsing, order dates, address standardization |\n| **Real Estate** | Property addresses, listing dates, price normalization, geo fields |\n\n---\n\n## Transform Library (76 transforms)\n\n### Text Transforms (18)\n| Transform | What It Does |\n|-----------|-------------|\n| `strip` | Trim whitespace |\n| `lowercase` / `uppercase` | Case conversion |\n| `title_case` | Proper casing (\"john smith\" -> \"John Smith\") |\n| `normalize_unicode` | NFKD normalization, strip accents |\n| `normalize_quotes` | Smart/curly quotes -> straight quotes |\n| `collapse_whitespace` | Multiple spaces -> single space |\n| `truncate:N` | Limit to N characters |\n| `remove_punctuation` | Strip punctuation characters |\n| `remove_html_tags` | Strip HTML markup from scraped data |\n| `remove_urls` | Strip URLs from free-text fields |\n| `remove_digits` | Strip numeric characters from text |\n| `remove_emojis` | Strip emoji characters |\n| `fix_mojibake` | Fix common UTF-8/Latin-1 encoding garbling |\n| `normalize_line_endings` | Normalize \\r\\n and \\r to \\n |\n| `extract_numbers` | Pull numeric values from mixed text |\n| `pad_left:N` / `pad_right:N` | Pad to fixed width (account numbers, IDs) |\n\n### Phone Transforms (5)\n| Transform | What It Does |\n|-----------|-------------|\n| `phone_e164` | Any format -> +15550123456 |\n| `phone_national` | Any format -> (555) 012-3456 |\n| `phone_digits` | Strip to digits only |\n| `phone_validate` | Flag invalid numbers |\n| `phone_country_code` | Extract country calling code |\n\n### Name Transforms (8)\n| Transform | What It Does |\n|-----------|-------------|\n| `split_name` | \"John Smith\" -> first: \"John\", last: \"Smith\" |\n| `split_name_reverse` | \"Smith, John\" -> first: \"John\", last: \"Smith\" |\n| `strip_titles` / `strip_suffixes` | Remove Mr., Mrs., Dr., MD, PhD, etc. |\n| `name_proper` | \"mcdonald\" -> \"McDonald\", \"o'brien\" -> \"O'Brien\" |\n| `initial_expand` | Flag names with initials for review |\n| `nickname_standardize` | \"Bob\" -> \"Robert\", \"Bill\" -> \"William\" |\n| `merge_name` | Combine first_name + last_name into full_name |\n\n### Address Transforms (8)\n| Transform | What It Does |\n|-----------|-------------|\n| `address_standardize` | \"Street\" -> \"St\", \"Avenue\" -> \"Ave\" |\n| `address_expand` | \"St\" -> \"Street\", \"Ave\" -> \"Avenue\" |\n| `state_abbreviate` / `state_expand` | \"Pennsylvania\" <-> \"PA\" |\n| `zip_normalize` | Zero-pad, strip +4, validate |\n| `split_address` | Single line -> street, city, state, zip |\n| `country_standardize` | \"United States\" / \"USA\" -> \"US\" (ISO 3166) |\n| `unit_normalize` | \"Apt\" / \"Apartment\" / \"#\" -> \"Unit\" |\n\n### Date Transforms (13)\n| Transform | What It Does |\n|-----------|-------------|\n| `date_iso8601` | Any format -> 2024-03-15 |\n| `datetime_iso8601` | Any format -> 2024-03-15T15:30:00 |\n| `date_us` / `date_eu` | Regional format output |\n| `date_parse` | Auto-detect and normalize to ISO 8601 |\n| `age_from_dob` | Date of birth -> age in years |\n| `extract_year` / `extract_month` / `extract_day` | Decompose dates |\n| `extract_quarter` | Date -> Q1/Q2/Q3/Q4 |\n| `extract_day_of_week` | Date -> Monday, Tuesday, etc. |\n| `date_shift` | Add/subtract days (anonymization) |\n| `date_validate` | Flag invalid dates as boolean |\n\n### Categorical Transforms (6)\n| Transform | What It Does |\n|-----------|-------------|\n| `category_auto_correct` | Fuzzy-match misspellings to canonical values |\n| `category_standardize` | Map variants to canonical values |\n| `category_from_file` | Load mapping from CSV/YAML file |\n| `boolean_normalize` | \"Yes\"/\"Y\"/\"1\"/\"True\" -> true |\n| `gender_standardize` | \"Male\"/\"M\"/\"Female\"/\"F\" -> M/F |\n| `null_standardize` | \"N/A\"/\"NULL\"/\"none\" -> null |\n\n### Numeric Transforms (9)\n| Transform | What It Does |\n|-----------|-------------|\n| `currency_strip` | \"$1,234.56\" -> 1234.56 |\n| `percentage_normalize` | \"85%\" -> 0.85 |\n| `round:N` | Round to N decimal places |\n| `clamp` | Constrain values to a min/max range |\n| `to_integer` | Parse string to int, truncating decimals |\n| `abs_value` | Absolute value |\n| `fill_zero` | Replace nulls with 0 |\n| `comma_decimal` | European format \"1.234,56\" -> 1234.56 |\n| `scientific_to_decimal` | \"1.5e3\" -> 1500.0 |\n\n### Email Transforms (4)\n| Transform | What It Does |\n|-----------|-------------|\n| `email_lowercase` | Normalize to lowercase |\n| `email_normalize` | Strip +tags, strip Gmail dots, lowercase |\n| `email_extract_domain` | user@example.com -> example.com |\n| `email_validate` | Flag invalid email format |\n\n### Identifier Transforms (3)\n| Transform | What It Does |\n|-----------|-------------|\n| `ssn_format` | Normalize to XXX-XX-XXXX |\n| `ssn_mask` | Redact to \\*\\*\\*-\\*\\*-1234 |\n| `ein_format` | Normalize to XX-XXXXXXX |\n\n### URL Transforms (2)\n| Transform | What It Does |\n|-----------|-------------|\n| `url_normalize` | Lowercase domain, ensure scheme, strip trailing slash |\n| `url_extract_domain` | Extract domain from URL |\n\n---\n\n## Special Modes\n\n### Strict Mode\n\nFail immediately if any transform error occurs — useful in CI or production pipelines:\n\n```bash\ngoldenflow transform data.csv --strict\n```\n\nExits with code 1 and prints the first 5 errors if any transform fails.\n\n### LLM Mode\n\nUse an LLM to enhance categorical corrections and handle edge cases that fuzzy matching misses:\n\n```bash\ngoldenflow transform data.csv --llm\n```\n\nRequires `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` in your environment. Falls back to standard transforms gracefully.\n\n### Auto-Correct\n\n`category_auto_correct` uses fuzzy matching to fix misspelled categorical values automatically. It is suppressed on high-cardinality columns (>10% unique values) to avoid false positives.\n\n```\n\"actve\" -> \"active\"\n\"Pennsylvnia\" -> \"Pennsylvania\"\n\"Unted States\" -> \"United States\"\n```\n\n---\n\n## YAML Config\n\nFor repeatable pipelines:\n\n```yaml\n# goldenflow.yaml\nsource: customers.csv\noutput: customers_clean.csv\n\ntransforms:\n  - column: name\n    ops: [strip, title_case]\n  - column: email\n    ops: [lowercase, strip]\n  - column: phone\n    ops: [phone_e164]\n  - column: state\n    ops: [state_abbreviate]\n  - column: signup_date\n    ops: [date_iso8601]\n\nrenames:\n  email_address: email\n  phone_number: phone\n\ndrop: [internal_id, temp_notes]\n\ndedup:\n  columns: [email]\n  keep: first\n```\n\n```bash\ngoldenflow transform customers.csv -c goldenflow.yaml\n```\n\nGenerate a config from your data automatically:\n\n```bash\ngoldenflow learn data.csv -o config.yaml\n```\n\n---\n\n## Python API\n\n```python\nimport goldenflow\n\n# Zero-config\nresult = goldenflow.transform_file(\"messy_data.csv\")\nprint(result.df)          # Clean Polars DataFrame\nprint(result.manifest)    # Audit trail\n\n# With config\nfrom goldenflow import GoldenFlowConfig, TransformSpec, TransformEngine\n\nconfig = GoldenFlowConfig(\n    transforms=[\n        TransformSpec(column=\"phone\", ops=[\"phone_e164\"]),\n        TransformSpec(column=\"date\", ops=[\"date_iso8601\"]),\n    ]\n)\nengine = TransformEngine(config=config)\nresult = engine.transform_df(df)\n```\n\n### Jupyter Notebook Support\n\n`TransformResult`, `Manifest`, and `DatasetProfile` all have `_repr_html_()` — they render as rich HTML tables automatically in Jupyter:\n\n```python\nimport goldenflow\n\nresult = goldenflow.transform_file(\"messy_data.csv\")\nresult           # renders as HTML table in Jupyter\nresult.manifest  # renders transform audit trail\n```\n\n---\n\n## TypeScript / JavaScript\n\nGoldenFlow has a full TypeScript port with feature parity — same 83 transforms, same engine, same config format. The core is **edge-safe** (runs in browsers, Cloudflare Workers, Vercel Edge) with a Node layer for file I/O and CLI.\n\n### Install\n\n```bash\nnpm install goldenflow\n```\n\n### CLI\n\n```bash\nnpx goldenflow-js transform data.csv              # Zero-config\nnpx goldenflow-js transform data.csv -c config.yaml  # With config\nnpx goldenflow-js profile data.csv                 # Column profiles\nnpx goldenflow-js learn data.csv -o config.yaml    # Generate config\nnpx goldenflow-js diff before.csv after.csv        # Compare files\nnpx goldenflow-js map -s source.csv -t target.csv  # Schema mapping\nnpx goldenflow-js stream large.csv --chunk-size 50000  # Streaming\nnpx goldenflow-js demo                             # Generate sample data\nnpx goldenflow-js history                          # Show recent runs\n```\n\n### TypeScript API\n\n```typescript\nimport { TransformEngine, makeConfig } from \"goldenflow\";\n\n// Zero-config — auto-detect and fix\nconst engine = new TransformEngine();\nconst result = engine.transformDf([\n  { name: \"  John Smith  \", email: \"JOHN@EXAMPLE.COM\", phone: \"(555) 123-4567\" },\n  { name: \"DR. JANE DOE\", email: \"  jane+work@gmail.com  \", phone: \"555.987.6543\" },\n]);\n\nconsole.log(result.rows);\n// [\n//   { name: \"John Smith\", email: \"john@example.com\", phone: \"+15551234567\" },\n//   { name: \"Jane Doe\", email: \"jane@gmail.com\", phone: \"+15559876543\" },\n// ]\nconsole.log(result.manifest.records.length); // transforms applied\n```\n\n```typescript\n// Configured — explicit transforms per column\nconst engine = new TransformEngine({\n  transforms: [\n    { column: \"phone\", ops: [\"phone_e164\"] },\n    { column: \"email\", ops: [\"strip\", \"email_normalize\"] },\n    { column: \"name\", ops: [\"strip\", \"title_case\"] },\n    { column: \"state\", ops: [\"state_abbreviate\"] },\n    { column: \"price\", ops: [\"currency_strip\"] },\n    { column: \"signup_date\", ops: [\"date_iso8601\"] },\n  ],\n  renames: { email_address: \"email\" },\n  drop: [\"internal_id\"],\n  dedup: { columns: [\"email\"], keep: \"first\" },\n});\nconst result = engine.transformDf(rows);\n```\n\n```typescript\n// Schema mapping\nimport { SchemaMapper } from \"goldenflow\";\n\nconst mapper = new SchemaMapper();\nconst mappings = mapper.map(\n  [{ fname: \"John\", lname: \"Smith\", email_address: \"j@e.com\" }],\n  [{ first_name: \"\", last_name: \"\", email: \"\" }],\n);\n// [{ source: \"fname\", target: \"first_name\", confidence: 0.95 }, ...]\n```\n\n```typescript\n// Streaming large datasets\nimport { StreamProcessor } from \"goldenflow\";\n\nconst processor = new StreamProcessor({ transforms: [{ column: \"name\", ops: [\"strip\"] }] });\nfor (const result of processor.streamRows(largeDataset, 10_000)) {\n  await writeChunk(result.rows);\n}\n```\n\n```typescript\n// Profiling\nimport { profileDataframe } from \"goldenflow\";\n\nconst profile = profileDataframe(rows, \"customers.csv\");\nfor (const col of profile.columns) {\n  console.log(`${col.name}: ${col.inferredType}, ${col.nullCount} nulls, ${col.uniqueCount} unique`);\n}\n```\n\n```typescript\n// Edge-safe import (browsers, Workers, Edge Runtime)\nimport { TransformEngine } from \"goldenflow/core\";\n\n// Node-only import (includes file I/O, MCP, CLI)\nimport { readFile, TransformEngine } from \"goldenflow/node\";\n```\n\n### MCP Server (TypeScript)\n\n```typescript\nimport { TOOL_DEFINITIONS, handleTool } from \"goldenflow/node\";\n\n// TOOL_DEFINITIONS: 10 MCP tools for Claude Desktop\n// handleTool(\"transform\", { path: \"data.csv\" }) → JSON string\n```\n\n### REST API (TypeScript)\n\n```typescript\nimport { runServer } from \"goldenflow/node\";\nrunServer(8000); // Starts HTTP server with /health, /transforms, /transform\n```\n\n---\n\n## Public API (34 exports)\n\n```python\nfrom goldenflow import (\n    # Core engine\n    TransformEngine, TransformResult,\n    # Config\n    GoldenFlowConfig, TransformSpec, SplitSpec, FilterSpec, DedupSpec, MappingSpec,\n    # Convenience\n    transform_file, transform_df,\n    # Manifest\n    Manifest, TransformRecord, TransformError,\n    # Profiler\n    DatasetProfile, ColumnProfile,\n    # Selector & differ\n    select_transforms, diff_dataframes, DiffResult,\n    # Transform registry\n    TransformInfo, register_transform, get_transform, list_transforms, parse_transform_name,\n    # Mapping\n    SchemaMapper, ColumnMapping,\n    # Config helpers\n    load_config, save_config, merge_configs, learn_config,\n    # Domains\n    DomainPack, load_domain,\n    # Connectors\n    read_file, write_file,\n)\n```\n\n---\n\n## Integrations\n\n### REST API\n\n```bash\ngoldenflow serve --host 0.0.0.0 --port 8000\n```\n\nPOST CSV data, get transformed CSV back. Built with FastAPI.\n\n### MCP Server\n\n```bash\ngoldenflow mcp-serve\n```\n\nExposes GoldenFlow as an MCP tool for Claude Desktop. Configure in your Claude Desktop settings.\n\n### TUI\n\n```bash\ngoldenflow interactive data.csv\n```\n\nFull-featured terminal UI built with Textual. Browse profiles, apply transforms, preview results.\n\n## Remote MCP Server\n\nGoldenFlow is available as a hosted MCP server on [Smithery](https://smithery.ai/servers/benzsevern/goldenflow) — connect from any MCP client without installing anything.\n\n**Claude Desktop / Claude Code:**\n```json\n{\n  \"mcpServers\": {\n    \"goldenflow\": {\n      \"url\": \"https://goldenflow-mcp-production.up.railway.app/mcp/\"\n    }\n  }\n}\n```\n\n**Local server:**\n```bash\npip install goldenflow[mcp]\ngoldenflow mcp-serve\n```\n\n10 tools available: transform files, auto-map schemas, profile columns, generate configs, diff before/after, apply domain packs.\n\n---\n\n## Part of the Golden Suite\n\n| Tool | Purpose | Python | TypeScript |\n|------|---------|--------|------------|\n| [GoldenCheck](https://github.com/benzsevern/goldencheck) | Validate & profile data quality | `pip install goldencheck` | `npm install goldencheck` |\n| [GoldenFlow](https://github.com/benzsevern/goldenflow) | Transform & standardize data | `pip install goldenflow` | `npm install goldenflow` |\n| [GoldenMatch](https://github.com/benzsevern/goldenmatch) | Deduplicate & match records | `pip install goldenmatch` | — |\n| [GoldenPipe](https://github.com/benzsevern/goldenpipe) | Orchestrate the full pipeline | `pip install goldenpipe` | — |\n\n```\nRaw Data\n   |\n   v\n+--------------+\n|  GoldenCheck |  <- Discover quality issues\n|  goldencheck |\n|  scan data   |\n+------+-------+\n       | findings\n       v\n+--------------+\n|  GoldenFlow  |  <- Fix issues, standardize, reshape\n|  goldenflow  |\n|  transform   |\n+------+-------+\n       | clean data\n       v\n+--------------+\n|  GoldenMatch |  <- Deduplicate, match, create golden records\n|  goldenmatch |\n|  dedupe      |\n+------+-------+\n       | golden records\n       v\n   Clean, deduplicated,\n   production-ready data\n```\n\nChain them:\n\n```bash\ngoldencheck scan data.csv | goldenflow transform --from-findings | goldenmatch dedupe\n```\n\n---\n\n## Performance\n\nBuilt on [Polars](https://pola.rs/) (Rust-backed DataFrames). Transforms use a hybrid approach: native Polars expressions stay in the Rust engine for simple transforms (strip, lowercase), while complex transforms (phone parsing, date parsing) use optimized Python via `map_batches`.\n\n---\n\n## Benchmarks\n\nGoldenFlow scores **100/100** on the [DQBench](https://github.com/benzsevern/dqbench) transform benchmark across all three tiers (customer database, e-commerce, healthcare claims).\n\n```bash\npip install dqbench\ndqbench run goldenflow\n```\n\n---\n\n## Why GoldenFlow?\n\n| | GoldenFlow | pandas scripts | [Great Expectations](https://greatexpectations.io/) | [dbt](https://www.getdbt.com/) | [Dataprep.Clean](https://docs.dataprep.ai/user_guide/clean/) |\n|---|---|---|---|---|---|\n| Zero-config transforms | Yes (auto-detect) | No | No (validation only) | No (SQL transforms) | Partial |\n| 76 built-in transforms (11 categories) | Yes | Manual | No (validator, not transformer) | Via SQL | ~30 cleaners |\n| Domain packs (healthcare, finance...) | 5 built-in | No | No | No | No |\n| Schema mapping | Auto + manual | Manual | No | Via ref/source | No |\n| Audit trail (manifest) | Automatic JSON | Manual | No | Via logs | No |\n| Streaming / large files | Built-in | Manual chunking | No | Yes (warehouse) | No |\n| MCP server | Yes | No | No | No | No |\n| Polars-native | Yes | No (pandas) | No (pandas/Spark) | No (SQL) | No (pandas) |\n| DQBench transform score | 100/100 | N/A | N/A | N/A | N/A |\n\nGoldenFlow is purpose-built for the transform step between validation and matching — not a general ETL tool. It turns messy data into clean, standardized data automatically.\n\n---\n\n## Error Handling\n\nGoldenFlow catches errors at the CLI boundary and shows friendly, actionable messages — no raw stack traces. Individual transform errors are captured in the manifest rather than crashing the run. Use `--strict` to change this behavior.\n\n---\n\n## Progress Bars\n\nLong-running operations (streaming, watch mode, scheduling) display a Rich progress spinner showing batch count, rows processed, and estimated completion.\n\n---\n\n**GitHub:** [github.com/benzsevern/goldenflow](https://github.com/benzsevern/goldenflow)\n**Author:** [Ben Severn](https://bensevern.dev)\n**License:** MIT\n**Python:** 3.11+ | **Node.js:** 20+ | **npm:** [goldenflow](https://www.npmjs.com/package/goldenflow) | **PyPI:** [goldenflow](https://pypi.org/project/goldenflow/)\n",
  "bytes": 27101,
  "sha": "c641dee88d94c1f376e5ae35910bb5f139ef75bd475d199879e6f992142ff644",
  "repo_slug": "benseverndev-oss/goldenflow",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_benseverndev_oss_goldenflow_51ca01f9/readme"
}