> ## Documentation Index
> Fetch the complete documentation index at: https://ritika-fa61c43f.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CRMPipelineAction: Agent Action Payload Model Reference

> Complete field reference for CRMPipelineAction — the Pydantic model sent in POST /step, covering all 13 fields and which action_type requires each.

`CRMPipelineAction` is the Pydantic model serialized as JSON and sent in the body of every `POST /step` request. It defines the complete action space available to the agent — from inspecting raw data and applying column-level transformations, to merging DataFrames, executing SQL, and finally submitting the cleaned pipeline for grading. Every field is declared on the model; fields irrelevant to the current `action_type` must be omitted or set to `null` — the server strips `None` values automatically when using `model_dump_json(exclude_none=True)`.

## Base Class

`CRMPipelineAction` extends `openenv.core.env_server.Action`, which itself extends Pydantic's `BaseModel`. If the `openenv` package is not installed, the server falls back to a plain `BaseModel` stub, so the serialization contract is identical in both environments.

```python theme={null}
# Inheritance chain
from openenv.core.env_server import Action   # or BaseModel fallback
from pydantic import BaseModel, Field

class CRMPipelineAction(Action):
    ...
```

## Type Definition

The following TypeScript-style interface gives you the full field surface at a glance:

```typescript theme={null}
interface CRMPipelineAction {
  action_type: PipelineActionType;  // required — always present
  source?: string;
  source2?: string;
  column?: string;
  standardization_strategy?: StandardizationStrategy;
  missing_strategy?: MissingStrategy;
  deduplication_strategy?: DeduplicationStrategy;
  fallback_value?: string;
  join_key?: string;
  conflict_rule?: ConflictRule;
  final_source?: string;
  query?: string;
  output_table?: string;
}
```

## Fields

**action\_type** `PipelineActionType` *required*

The type of operation to perform. This is the only required field and acts as the discriminator that determines which other fields the server expects. Must be one of the eight `PipelineActionType` enum values. See the [Enums reference](https://ritika-fa61c43f.mintlify.site/api/models/enums.md) for the complete list.

```json theme={null}
{ "action_type": "PROFILE_SOURCE", "source": "web_forms" }
```

**source** `string`

The primary DataFrame name to operate on. Must exactly match one of the strings in `available_sources` returned by the latest observation. Used by `VIEW_SOURCE`, `PROFILE_SOURCE`, `STANDARDIZE_COLUMN`, `HANDLE_MISSING`, `DEDUPLICATE`, and as the first join partner in `MERGE_SOURCES`.

```json theme={null}
{ "action_type": "VIEW_SOURCE", "source": "web_forms" }
```

**source2** `string`

The secondary DataFrame name for `MERGE_SOURCES`. Must also exist in `available_sources`. The two sources are merged on `join_key` using an outer join, and the result is written to `output_table`.

```json theme={null}
{
  "action_type": "MERGE_SOURCES",
  "source": "web_forms",
  "source2": "legacy_db",
  "join_key": "customer_id",
  "output_table": "merged_output"
}
```

**column** `string`

The column name within `source` to apply a column-level operation to. Required for `STANDARDIZE_COLUMN` and `HANDLE_MISSING`. Must match an actual column in the target DataFrame — the server raises a `ValueError` (surfaced as `"Error: ..."` in `last_action_feedback`) if the column does not exist.

```json theme={null}
{
  "action_type": "STANDARDIZE_COLUMN",
  "source": "web_forms",
  "column": "email",
  "standardization_strategy": "LOWERCASE_STRIP"
}
```

**standardization\_strategy** `StandardizationStrategy`

The transformation strategy for `STANDARDIZE_COLUMN`. Required when `action_type` is `STANDARDIZE_COLUMN`. Ignored for all other action types. See [StandardizationStrategy](https://ritika-fa61c43f.mintlify.site/api/models/enums.md#standardizationstrategy) for value semantics.

| Value | Effect |
| - | - |
| `LOWERCASE_STRIP` | `.lower().strip()` on all string values |
| `TO_DATETIME_ISO` | Parse varied date formats → `YYYY-MM-DDTHH:MM:SS`, empty string on failure |
| `EXTRACT_NUMBERS` | Strip non-digits and reformat as `+<digits>` (E.164 pre-processing) |
| `PHONE_E164` | Direct phone-to-E.164 conversion |

**missing\_strategy** `MissingStrategy`

The null-handling strategy for `HANDLE_MISSING`. Required when `action_type` is `HANDLE_MISSING`. See [MissingStrategy](https://ritika-fa61c43f.mintlify.site/api/models/enums.md#missingstrategy) for value semantics.

| Value | Effect |
| - | - |
| `FILL_MEAN` | Replace nulls with the column's numeric mean |
| `FILL_MODE` | Replace nulls with the column's most frequent value |
| `FILL_VALUE` | Replace nulls with the literal string in `fallback_value` |
| `DROP_ROW` | Drop every row where this column is null |

**deduplication\_strategy** `DeduplicationStrategy`

The deduplication heuristic for `DEDUPLICATE`. Required when `action_type` is `DEDUPLICATE`. See [DeduplicationStrategy](https://ritika-fa61c43f.mintlify.site/api/models/enums.md#deduplicationstrategy) for matching logic.

| Value | Matching Logic |
| - | - |
| `EXACT_EMAIL` | `drop_duplicates(subset=["email"])` |
| `FUZZY_NAME_PHONE` | Lowercased+stripped name and digit-only phone together |

**fallback\_value** `string`

The literal replacement string used when `missing_strategy` is `FILL_VALUE`. Ignored for all other missing strategies. Provide an empty string `""` to fill nulls with blanks rather than a visible placeholder — this is the correct approach for the `phone` and `signup_date` columns in Task 1 when values are unrecoverable.

```json theme={null}
{
  "action_type": "HANDLE_MISSING",
  "source": "web_forms",
  "column": "phone",
  "missing_strategy": "FILL_VALUE",
  "fallback_value": ""
}
```

**join\_key** `string`

The column name to join on for `MERGE_SOURCES`. The column must exist in both `source` and `source2`. The server normalizes the key values (`.lower().strip()`) before merging to handle case and whitespace inconsistencies between sources.

> [!WARNING]
>
> If `join_key` is absent from either DataFrame, the merge fails immediately and `last_action_feedback` returns `"Merge failed: key '<key>' missing from one of the sources."` with a `-0.05` reward penalty.

**conflict\_rule** `ConflictRule`

The conflict resolution strategy for overlapping non-key columns during `MERGE_SOURCES`. Optional — defaults to `COALESCE` if omitted. See [ConflictRule](https://ritika-fa61c43f.mintlify.site/api/models/enums.md#conflictrule).

| Value | Behavior |
| - | - |
| `PREFER_S1` | Take the value from `source`; fall back to `source2` if null |
| `PREFER_S2` | Take the value from `source2`; fall back to `source` if null |
| `COALESCE` | Take the first non-null value from either source (default) |

> [!TIP]
>
> For Task 3, the observation's `conflict_rules` field tells you the per-column resolution policy (e.g., `"email": "prefer_salesforce"`). Map those strings to the corresponding `ConflictRule` values when building separate per-column merge actions.

**final\_source** `string`

The name of the DataFrame to submit as the pipeline's final output for `SUBMIT_PIPELINE`. Must exist in `available_sources`. The server captures `self._sources[final_source]` and passes it to the grader, which compares it against the hidden ground-truth snapshot.

> [!WARNING]
>
> Submission is blocked if `step_count < 3`. Attempting early submission returns a `-0.15` reward penalty and `done=false`. You must perform at least three cleaning actions (e.g., PROFILE\_SOURCE + STANDARDIZE\_COLUMN + HANDLE\_MISSING) first.

**query** `string`

The raw SQL `SELECT` query string for `EXECUTE_SQL`. The server loads every DataFrame in `available_sources` into an in-memory SQLite database using the source name as the table name, executes your query, and writes the result to `output_table`.

```json theme={null}
{
  "action_type": "EXECUTE_SQL",
  "query": "SELECT * FROM web_forms WHERE email IS NOT NULL",
  "output_table": "web_forms_clean"
}
```

> [!WARNING]
>
> Only `SELECT` queries are permitted. `DROP`, `DELETE`, `UPDATE`, `INSERT`, `ALTER`, `CREATE`, and `TRUNCATE` are blocked and return a `-0.1` reward penalty. Queries that do not begin with `SELECT` are rejected outright.

**output\_table** `string`

The name under which the result DataFrame is registered in `available_sources` after `EXECUTE_SQL` or `MERGE_SOURCES`. Once written, you can reference `output_table` in subsequent actions as a normal source name. If omitted for `EXECUTE_SQL`, the result is saved as `"sql_output"`.

```json theme={null}
{
  "action_type": "EXECUTE_SQL",
  "query": "SELECT customer_id, lower(email) AS email FROM web_forms",
  "output_table": "web_forms_normalized"
}
```

***

## Required Fields Per Action Type

The following table summarizes exactly which fields are required and which are optional for each `action_type`. Sending extra fields is harmless — they are silently ignored.

| `action_type` | Required Fields | Optional Fields |
| - | - | - |
| `VIEW_SOURCE` | `source` | — |
| `PROFILE_SOURCE` | `source` | — |
| `STANDARDIZE_COLUMN` | `source`, `column`, `standardization_strategy` | — |
| `HANDLE_MISSING` | `source`, `column`, `missing_strategy` | `fallback_value` |
| `DEDUPLICATE` | `source`, `deduplication_strategy` | — |
| `MERGE_SOURCES` | `source`, `source2`, `join_key`, `output_table` | `conflict_rule` |
| `EXECUTE_SQL` | `query`, `output_table` | — |
| `SUBMIT_PIPELINE` | `final_source` | — |

> [!NOTE]
>
> `fallback_value` is only meaningful when `missing_strategy` is `FILL_VALUE`. For `FILL_MEAN` and `FILL_MODE` it is ignored. For `DROP_ROW` it is also ignored.

***

## Usage Examples

```python theme={null}
from models import (
    CRMPipelineAction,
    PipelineActionType,
    StandardizationStrategy,
    MissingStrategy,
    DeduplicationStrategy,
    ConflictRule,
)

# ── 1. Profile a source to understand data quality ──────────────────────────
action = CRMPipelineAction(
    action_type=PipelineActionType.PROFILE_SOURCE,
    source="web_forms"
)

# ── 2. Standardize email column to lowercase + stripped ─────────────────────
action = CRMPipelineAction(
    action_type=PipelineActionType.STANDARDIZE_COLUMN,
    source="web_forms",
    column="email",
    standardization_strategy=StandardizationStrategy.LOWERCASE_STRIP
)

# ── 3. Standardize signup_date to ISO 8601 ───────────────────────────────────
action = CRMPipelineAction(
    action_type=PipelineActionType.STANDARDIZE_COLUMN,
    source="web_forms",
    column="signup_date",
    standardization_strategy=StandardizationStrategy.TO_DATETIME_ISO
)

# ── 4. Handle missing phone values with an empty-string fallback ─────────────
action = CRMPipelineAction(
    action_type=PipelineActionType.HANDLE_MISSING,
    source="web_forms",
    column="phone",
    missing_strategy=MissingStrategy.FILL_VALUE,
    fallback_value=""
)

# ── 5. Deduplicate by exact email match ──────────────────────────────────────
action = CRMPipelineAction(
    action_type=PipelineActionType.DEDUPLICATE,
    source="web_forms",
    deduplication_strategy=DeduplicationStrategy.EXACT_EMAIL
)

# ── 6. Merge two sources on customer_id, preferring the second source ────────
action = CRMPipelineAction(
    action_type=PipelineActionType.MERGE_SOURCES,
    source="web_forms",
    source2="legacy_db",
    join_key="customer_id",
    conflict_rule=ConflictRule.PREFER_S2,
    output_table="merged_output"
)

# ── 7. Execute a SQL filter query ────────────────────────────────────────────
action = CRMPipelineAction(
    action_type=PipelineActionType.EXECUTE_SQL,
    query="SELECT * FROM web_forms WHERE email IS NOT NULL",
    output_table="web_forms_clean"
)

# ── 8. Submit the final cleaned pipeline ─────────────────────────────────────
action = CRMPipelineAction(
    action_type=PipelineActionType.SUBMIT_PIPELINE,
    final_source="web_forms_clean"
)
```

***

## JSON Serialization

When sending actions to `POST /step`, use `model_dump_json(exclude_none=True)` to strip all `None` fields and produce a minimal, clean payload. This matches the server's expected format and avoids validation noise from null fields irrelevant to the current `action_type`.

```python theme={null}
import json
import httpx

action = CRMPipelineAction(
    action_type=PipelineActionType.STANDARDIZE_COLUMN,
    source="web_forms",
    column="email",
    standardization_strategy=StandardizationStrategy.LOWERCASE_STRIP
)

# Produces: {"action_type":"STANDARDIZE_COLUMN","source":"web_forms","column":"email","standardization_strategy":"LOWERCASE_STRIP"}
payload = json.loads(action.model_dump_json(exclude_none=True))

response = httpx.post("http://localhost:8080/step", json=payload)
```

The serialized payload for the example above:

```json theme={null}
{
  "action_type": "STANDARDIZE_COLUMN",
  "source": "web_forms",
  "column": "email",
  "standardization_strategy": "LOWERCASE_STRIP"
}
```

Because all five enum types inherit from `str`, their values are already plain strings in the JSON output — no extra conversion is required.

> [!TIP]
>
> The `CRMDataPipelineEnvClient._step_payload()` method in `client.py` calls `model_dump_json(exclude_none=True)` automatically, so if you use the provided client you never need to serialize manually.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.