Skip to main content
POST /step is the primary interaction endpoint. Each call deserializes the request body into a CRMPipelineAction Pydantic model, increments the internal step counter, dispatches to the matching handler function, mutates the in-memory Pandas DataFrames in place, and returns a CRMStepResult carrying the updated CRMPipelineObservation, a scalar reward, and a done flag. You call this endpoint repeatedly — profiling, cleaning, merging — until you are ready to submit.

Request Format

Only action_type is universally required. All other fields are conditionally required depending on the action type, as documented below.

Action Types and Examples

VIEW_SOURCE

Retrieves a markdown-formatted preview of the top 3 rows of a source DataFrame. Returns reward = 0.0. Use this to inspect raw data before deciding which columns need cleaning. Request:
Response:

PROFILE_SOURCE

Generates a per-column data quality report showing the dtype and null count of every column. Returns reward = +0.02. Always profile before cleaning — the report is written to data_quality_report in the observation. Request:
Response:

STANDARDIZE_COLUMN

Applies a deterministic transformation to a single column in a source DataFrame. The mutation is performed in place — the source DataFrame is permanently updated in server memory. Returns reward between +0.01 and +0.05, scaled by the fraction of rows that were actually changed. Available strategies are defined by the StandardizationStrategy enum: Request (lowercase email):
Response:
Request (phone E.164):
Request (date ISO 8601):

HANDLE_MISSING

Resolves null values in a single column using one of the MissingStrategy options. Returns reward proportional to the fraction of nulls resolved (minimum +0.01). Request:
Response:
Request (fill with empty string):

DEDUPLICATE

Removes duplicate rows from a source DataFrame based on the chosen DeduplicationStrategy. The mutation is saved back to the source. Returns reward = removed_rows / original_rows × 0.2. Request:
Response:

MERGE_SOURCES

Performs an outer join of two source DataFrames on a shared key column. The result is always stored under the fixed name merged_output, which then appears in available_sources. Returns reward = +0.05 on success or -0.05 if the join key is missing from either source. Conflict resolution for overlapping columns is controlled by the ConflictRule enum:
For Task 3, read the conflict_rules dictionary from the reset observation to determine which ConflictRule to pass per column. The hidden truth was built using those exact priority rules — mismatched rules will reduce your grader score.
Request:
Response:

EXECUTE_SQL

Executes a SELECT SQL query across all currently loaded sources using an in-memory SQLite connection. Every source DataFrame is registered as a table under its source name. The result is stored as a new source under output_table (defaulting to "sql_output"). Returns reward = +0.1 on success.
Only SELECT queries are permitted. Any query beginning with DROP, DELETE, UPDATE, INSERT, ALTER, CREATE, or TRUNCATE is rejected with reward = -0.1 and a blocked-action feedback message. This is enforced server-side and cannot be bypassed.
Request:
Response:
Multi-table join example:

SUBMIT_PIPELINE

Marks the end of the episode. The final_source DataFrame is frozen as the agent’s submission. The server computes a preliminary schema_match_ratio — the fraction of schema_target columns that are present in the submitted DataFrame — and returns reward = 0.2 × schema_match_ratio. The terminal grader score is computed separately via /grader/{episode_id}.
You must execute at least 3 steps (any combination of profile, standardize, handle missing, deduplicate, merge, SQL) before submitting. Submitting with step_count < 3 returns reward = -0.15 and done = false — the episode continues and you are penalized.
Request:
Response (step_count >= 3, success):
Response (early submission, step_count < 3):

Error Response Pattern

When any action raises an exception — invalid source name, missing column, malformed SQL, incorrect join key — the server catches the exception, sets reward = -0.05, and continues the episode with done = false.
Always check last_action_feedback for the human-readable error string when reward is negative.

Reward Reference


Request Field Reference

PipelineActionType
required
The operation to execute. Must be one of the PipelineActionType enum values: VIEW_SOURCE, PROFILE_SOURCE, STANDARDIZE_COLUMN, HANDLE_MISSING, DEDUPLICATE, MERGE_SOURCES, EXECUTE_SQL, SUBMIT_PIPELINE.
string
Name of the primary source DataFrame to operate on. Must be a value currently present in available_sources. Required for VIEW_SOURCE, PROFILE_SOURCE, STANDARDIZE_COLUMN, HANDLE_MISSING, DEDUPLICATE, and MERGE_SOURCES.
string
Name of the secondary source DataFrame. Required only for MERGE_SOURCES as the right-hand table in the outer join.
string
The column name within source to mutate. Required for STANDARDIZE_COLUMN and HANDLE_MISSING. Must be a column that exists in the DataFrame or the action returns reward = -0.05.
StandardizationStrategy
The transformation to apply to column. Required for STANDARDIZE_COLUMN. Enum values: LOWERCASE_STRIP, EXTRACT_NUMBERS, TO_DATETIME_ISO, PHONE_E164.
MissingStrategy
The strategy for handling nulls in column. Required for HANDLE_MISSING. Enum values: DROP_ROW, FILL_VALUE, FILL_MEAN, FILL_MODE.
DeduplicationStrategy
The heuristic for identifying duplicate rows. Required for DEDUPLICATE. Enum values: EXACT_EMAIL, FUZZY_NAME_PHONE.
string
The literal string value used to fill nulls when missing_strategy is FILL_VALUE. Pass "" to fill with an empty string. Ignored for other missing strategies.
string
The column name used as the join predicate for MERGE_SOURCES. Must exist in both source and source2 after the join-key normalization step (both sides are lowercased and stripped before matching).
ConflictRule
Governs how overlapping columns are resolved after the merge. Used only in MERGE_SOURCES. Enum values: PREFER_S1, PREFER_S2, COALESCE. Defaults to COALESCE if omitted.
string
The source name whose DataFrame is submitted as the agent’s final output. Required for SUBMIT_PIPELINE. Must be a value present in available_sources.
string
A raw SQL SELECT statement to execute against the in-memory SQLite database populated with all current sources as tables. Required for EXECUTE_SQL. Must begin with SELECT — any other statement verb is blocked and penalized.
string
The name under which the result DataFrame of an EXECUTE_SQL operation is stored and surfaced in available_sources. Defaults to "sql_output" if omitted. Note: MERGE_SOURCES always writes its output to the fixed name "merged_output" regardless of this field.