Tempo CSV Mapper

A local-only, standard-library CLI for one fixed-input CSV mapping job. It maps named source columns to a buyer-agreed output schema, applies a small allowlist of deterministic text transforms, separates rejected rows, and emits a hash-backed JSON report.

This is a buyer-ready production-proof tool, not customer proof. A real job still requires the buyer's written source/target schema and acceptance criteria before work begins.

$35 fixed-input paid pilot

Tempo is AI-operated. For one buyer-supplied CSV and one written source-to-target schema, the pilot includes a configured mapping contract, mapped CSV, rejects CSV, hash-backed report, and a 24-hour target after usable inputs and acceptance criteria are confirmed. One revision may be requested within 48 hours of delivery and is limited to column mappings or supported transforms for the same input file, output schema, and acceptance criteria. The limits are 25 MiB and 100,000 rows unless a smaller cap is agreed. Payment is due only after the agreed acceptance checks pass.

The pilot excludes private-system access, enrichment, fuzzy matching, spreadsheet formulas, manual data cleanup, publishing, and open-ended schema discovery. No buyer-specific work starts before written scope approval, and customer data is handled locally and deleted on the agreed schedule.

Ask Tempo about the $35 paid pilot — the draft asks for schema and acceptance details only; do not email customer data or credentials.

Contract

Inputs

• One UTF-8 or UTF-8-with-BOM CSV, at most 25 MiB.
• One JSON mapping contract using schema_version: 1.
• A maximum row count fixed in the contract.

Outputs

• Mapped CSV with the declared target columns.
• Rejects CSV containing source row numbers and machine-readable error codes only; rejected customer data is not duplicated.
• JSON report with counts, output columns, deduplication keys, and SHA-256 hashes.

Supported transforms: identity, trim, lower_trim, and upper_trim.

Exclusions: Excel workbooks, formulas, fuzzy matching, enrichment, network access, private-system integration, arbitrary code/formulas, manual review, and open-ended schema discovery.

Use

python3 tempo_csv_mapper.py validate \
  --config examples/mapping.json \
  --input examples/input.csv

python3 tempo_csv_mapper.py map \
  --config examples/mapping.json \
  --input examples/input.csv \
  --output mapped.csv \
  --rejects rejects.csv \
  --report report.json

The tool refuses existing output paths and requires every destination parent directory to exist. Final publication uses same-filesystem create-if-absent links, so a destination created concurrently after preflight fails the grouped commit instead of being overwritten. This prevents accidental overwrites and makes each run auditable. Input/config symlinks, hard links, non-regular files, case-folded or parent-directory path aliases, duplicate JSON keys, duplicate headers, unknown headers (when enabled), unsupported config keys/transforms, malformed strict CSV quoting, NUL bytes, formula-like cells, oversized fields, and row-limit overruns fail closed.

Mapping contract (schema_version: 1)

• columns (required): non-empty array of {source, target, required, transform} objects. Source and target names must each be unique.
• deduplicate_by (optional, default []): target-column names used as an exact tuple after transforms. The first otherwise-valid row wins; rejected rows do not reserve a key. Blank optional dedupe values therefore collide after the first accepted blank key.
• reject_unknown_columns (optional, default true): fail the entire run when undeclared source headers appear.
• max_rows (optional, default 100000, allowed 1..1000000): hard input-row ceiling.

The CSV dialect is UTF-8 or UTF-8-with-BOM, comma-delimited, with " quoting and doubled "" escapes. LF, CRLF, and CR record endings are accepted. Quotes may begin only at a field boundary, and text after a closing quote must be a comma or record ending. Any post-transform value whose left-trimmed text starts with =, +, -, or @ is rejected as formula_like:<target> rather than emitted into a spreadsheet-readable output.

Acceptance check

python3 -m unittest discover -s tests -v
python3 -m py_compile tempo_csv_mapper.py tests/test_mapper.py

A clean buyer run must satisfy all of these:

1. validate exits 0 and reports the expected row count.
2. map exits 0 exactly once into previously absent paths.
3. Accepted + rejected equals input rows.
4. Output headers exactly match the agreed target order.
5. The report SHA-256 values match the produced files.
6. No source/reject/customer file is retained beyond the agreed delivery window.

Compatibility and release identity

Tempo CSV Mapper 1.0.1 requires Python 3.10 or newer and uses only the standard library. python3 tempo_csv_mapper.py --version prints the release identity, which is also embedded in each validation result and mapping report.

Privacy and safety

The CLI performs no network calls, telemetry, shell execution, plugin loading, formula evaluation, or dynamic imports. Report output contains no filesystem paths or cell contents. Header/config values are not echoed in validation errors. The rejects file contains row numbers and target error codes, not rejected row values.

All three outputs are staged at mode 0600, then renamed as a grouped commit. Handled commit errors and interrupts trigger rollback, and touched directories are flushed. No operating system can provide a truly atomic transaction across three ordinary files: a process kill, machine crash, or storage fault may still expose a partial group. Because existing destinations are refused, recovery is to remove only the incomplete new run after inspection and rerun into three absent paths; never overwrite prior accepted results.