Natural Language to Reproducible Pandas Code
A data agent becomes reviewable when a plain-language request leaves behind executable code, explicit assumptions, output data, and validation evidence.
Evidence, retrieval, agents, and the paths that connect a question to a grounded answer.
Interactive model
From request to transformations
Toggle common transformations to see how raw columns become model-ready features or cleaned fields.
Live HTML simulation · adjust the controls and watch the computed output respond.
Interactive
Raw columns become model-ready signals through feature engineering
This is a simplified teaching model. Its displayed values are computed from the controls; the article explains where the model stops.
Site connection
The Data Cleaning Assistant reports a workflow that turns plain-English CSV cleaning requests into cleaned outputs and reusable pandas scripts.
Translation Is a Schema-and-Policy Problem
A request such as 'make hired a boolean and remove bad rows' leaves key questions unresolved: which strings count as true, what makes a row bad, how missing values should behave, whether row identity must be preserved, and which output is authoritative. Reproducible code must make those decisions visible.
A reviewable run should produce:
- A script with explicit inputs, transformations, and outputs.
- A cleaned dataset or other deterministic artifact.
- An audit summary with assumptions, before/after metrics, and validation results.
Reported Project Behavior and Recommended Contract
Project fact: the portfolio source says the Data Cleaning Assistant accepts a CSV and plain-English instructions, then returns a cleaned dataset plus the exact Python script. It reports a FastAPI and Google Gemini multi-agent backend, schema exploration, pandas/numpy code execution in a sandboxed environment with no `exec` or `eval` and whitelisted imports, visualization, statistical analysis, merging, regex, planning, and specialist routing.
The source demonstrates 'make the hired column a boolean' and reports that the agent ran `df['Hired'].astype(bool)` while the DataFrame shape stayed unchanged. That demonstration is not a generally correct parsing rule: in pandas/Python, a non-empty string such as `'False'` is truthy. The schema-first translation and validation policies below are recommendations for making such transformations dependable.
| Statement | Classification |
|---|---|
| The project returns cleaned data and a Python script | Reported project behavior |
| The portfolio reports whitelisted imports and no exec/eval | Reported project guardrail |
| Boolean conversion should use an explicit value map | Recommended correctness policy |
| Every run should pin pandas and record input/output hashes | Recommended reproducibility policy |
Compile Intent into an Explicit Transformation Plan
Before generating code, inspect column names, dtypes, representative values, null counts, uniqueness, and row identifiers. Translate the request into operations with preconditions and postconditions. If a consequential rule remains ambiguous, present the assumption or ask for clarification rather than guessing from a column name.
Separate cleaning from analysis. Cleaning standardizes representation, repairs or flags invalid values, and preserves lineage. Aggregation, modeling, and plotting may consume the cleaned data, but they should remain distinct steps so a user can rerun or reject one without silently changing another.
Analogy limit: generated code resembles a compiler output because it translates a higher-level request. Natural language lacks a formal grammar and complete semantics, so schema inspection, confirmation, and tests remain necessary.
| Natural-language intent | Required decision | Postcondition |
|---|---|---|
| Make hired a boolean | Accepted true/false tokens and null policy | Only True, False, or allowed NA remains |
| Remove bad rows | Formal invalidity predicate | Every removed row has a reason code |
| Deduplicate customers | Identity keys and keep rule | At most one row per selected key |
| Fill missing income | Imputation method and grouping | No target NA; imputation flags retained |
| Graph followers vs following | Numeric coercion and exclusion rules | Plot inputs and excluded rows are reported |
Reproducibility and Execution Safety
A reproducible script declares the input path or object, expected schema, dependency versions, ordered transformations, deterministic parameters, validation assertions, and output path. Record input and output hashes plus before/after row counts, dtypes, and null counts. Avoid hidden notebook state and broad `inplace` mutation; pandas 3.0's official Copy-on-Write behavior also means older assumptions about views, chained assignment, and side effects should not be carried across versions without testing.
Execution safety is a separate boundary from reproducibility. Recommended controls include a disposable working directory, read-only original input, narrow output directory, import allowlist, disabled network, resource and time limits, subprocess restrictions, file-size caps, and structured result capture. A ban on `exec`/`eval` and an import allowlist reduce risk but do not by themselves prove complete sandbox isolation.
| Risk | Guardrail | Evidence to retain |
|---|---|---|
| Wrong column assumption | Schema preview and explicit precondition | Observed columns and selected mapping |
| Silent row loss | Reason-coded filter and count assertion | Before/after counts by reason |
| Version-dependent behavior | Pinned environment and fixture tests | pandas version and test output |
| Filesystem escape | Isolated read/write mounts | Declared accessed paths |
| Non-reproducible output | Exact script, parameters, and hashes | Run manifest |
Worked Example
Input values in `Hired` are `['Yes', 'no', 'TRUE', '0', '', null]`. The user asks, 'make Hired a boolean and remove rows where the answer is blank.' An explicit policy maps `yes/true/1` to `True`, `no/false/0` to `False`, treats an empty string and null as missing, and removes only missing outcomes. The agent reports the policy before execution.
The generated script normalizes text with `str.strip().str.lower()`, maps through a fixed dictionary, stores the result using pandas' nullable `boolean` dtype, asserts that every non-missing normalized token was recognized, records two removed row IDs, and writes a new output instead of overwriting the upload. For the six illustrative rows, four remain: `[True, False, True, False]`.
Using `.astype(bool)` directly would be wrong for this string column because non-empty strings—including `'no'` and `'0'`—evaluate truthy. If an unexpected token such as `'maybe'` appears, the correct result is a failed validation or explicit unresolved category, not silent coercion.
| Raw value | Normalized | Output | Reason |
|---|---|---|---|
| Yes | yes | True | Explicit true token |
| no | no | False | Explicit false token |
| TRUE | true | True | Case normalized |
| 0 | 0 | False | Explicit false token |
| empty string | empty | removed | Declared missing-row policy |
| null | NA | removed | Declared missing-row policy |
Validation, Audit Output, and Limitations
Validate both structure and meaning: required columns, dtype expectations, allowed domains, key uniqueness, row-count bounds, missingness, distribution shifts, and invariants specific to the task. For grouping or imputation, remember that pandas GroupBy follows split-apply-combine and that count-like operations can differ in their handling of missing values; tests should encode the intended statistic rather than rely on a vague word such as 'count.'
Natural language cannot recover business rules that are absent from the request and data. A passing script can implement the wrong policy, a cleaned dataset can erase meaningful outliers, and deterministic code can reproduce a biased transformation perfectly. Preserve the original, expose changed cells or reason-coded row removals, and keep human review proportional to consequence.
Common Pitfalls
- Converting string booleans with `astype(bool)` and turning every non-empty string into True.
- Dropping rows under a vague 'bad row' rule without reason codes or before/after counts.
- Returning only a cleaned CSV without the exact script, environment, and assumptions.
- Assuming an import allowlist or a ban on exec/eval proves complete sandbox isolation.
- Using chained assignment or version-sensitive mutation without pinned pandas tests.
- Conflating cleaning with modeling and silently changing the analysis target.
- Presenting recommended validation and sandbox policies as reported project features.