> ## 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.

# CRMPipelineObservation: Parsing Agent Observations

> Complete reference for CRMPipelineObservation — the response model from POST /step and POST /reset, with field semantics and parsing examples.

`CRMPipelineObservation` is the structured payload your agent receives after every interaction with the environment. It is returned by both `POST /step` and `POST /reset`, wrapped inside a `CRMStepResult` container. Each observation gives you a complete picture of the environment state — what data sources are available, what the current view looks like, any data quality findings from profiling, and direct feedback on whether your last action succeeded or failed. Reading the observation carefully is how your agent decides its next move.

## Response Envelope

Every response from `POST /step` and `POST /reset` is wrapped in the `CRMStepResult` container. The `observation` key holds the `CRMPipelineObservation` fields, while `reward` and `done` are also hoisted to the top level for convenience:

```json theme={null}
{
  "observation": {
    "done": false,
    "reward": 0.02,
    "current_task_objective": "Normalize web_forms dataset",
    "schema_target": { ... },
    "available_sources": ["web_forms"],
    "current_view": "...",
    "data_quality_report": null,
    "last_action_feedback": "Profiled web_forms",
    "conflict_rules": null
  },
  "reward": 0.02,
  "done": false
}
```

> [!NOTE]
>
> The `CRMDataPipelineEnvClient._parse_result()` method in `client.py` reads from `payload["observation"]` first and falls back to the top-level `payload` if the key is absent. This means the client handles both the wrapped and flat formats transparently.

***

## Example Observation

The following is a representative `CRMPipelineObservation` JSON body after a successful `PROFILE_SOURCE` action on the `web_forms` source in Task 1:

```json theme={null}
{
  "done": false,
  "reward": 0.02,
  "current_task_objective": "Normalize web_forms dataset",
  "schema_target": {
    "customer_id": "string",
    "name": "string (stripped)",
    "email": "string (lowercase, stripped)",
    "signup_date": "string ISO 8601 or empty",
    "phone": "string E.164 format (+1...) or empty"
  },
  "available_sources": ["web_forms"],
  "current_view": "| customer_id | name | email | signup_date | phone |\n|---|---|---|---|---|\n| CUST_1001 | John Doe | JOHN.DOE@GMAIL.COM | 2023/05/15 | 15551234567 |",
  "data_quality_report": "- **customer_id**: type=object, nulls=0\n- **name**: type=object, nulls=2\n- **email**: type=object, nulls=9\n- **signup_date**: type=object, nulls=8\n- **phone**: type=object, nulls=11",
  "last_action_feedback": "Profiled web_forms",
  "conflict_rules": null
}
```

***

## Fields

**done** `boolean` *required*

`true` only after a successful `SUBMIT_PIPELINE` action that passes the minimum-steps guard (at least 3 prior cleaning actions). When `done` is `true`, the episode is over and the grader has captured your final DataFrame. Attempting to send further `POST /step` requests after `done=true` will start a new episode step, not a new episode — call `POST /reset` to begin fresh.

```python theme={null}
if result.done:
    print("Episode complete — check your score via POST /grader/{episode_id}")
```

**reward** `float | null`

The step reward earned for the action that produced this observation. Rewards are dense and action-specific:

| Action | Typical Reward |
| - | - |
| `PROFILE_SOURCE` | `+0.02` (fixed) |
| `STANDARDIZE_COLUMN` | `+0.01` to `+0.05` (proportional to rows improved) |
| `HANDLE_MISSING` | `+0.01` to `+0.10` (proportional to nulls resolved) |
| `DEDUPLICATE` | Up to `+0.20` (fraction of duplicates removed) |
| `MERGE_SOURCES` | `+0.05` on success |
| `EXECUTE_SQL` | `+0.10` on success |
| `SUBMIT_PIPELINE` | `+0.00` to `+0.20` (schema match ratio × 0.20) |
| Any error | `-0.05` (general); `-0.10` (SQL violation); `-0.15` (early submit) |

> [!NOTE]
>
> `reward` is `null` immediately after `POST /reset` because no action has been taken yet.

**current\_task\_objective** `string` *required*

A human-readable description of the active task. The string is set at episode reset time and does not change during the episode. Use it to understand what the grader will evaluate:

| `task_id` | `current_task_objective` |
| - | - |
| `t1` | `"Normalize web_forms dataset"` |
| `t2` | `"Deduplicate legacy_db dataset"` |
| `t3` | `"Merge Salesforce, Web Leads, Legacy databases"` |

The full task description including data quality expectations is embedded here — read it carefully at the start of each episode.

**schema\_target** `Dict[string, string]` *required*

The expected output schema the grader enforces. Keys are the column names your final DataFrame must contain; values are human-readable format descriptions. The grader performs exact string matching (case-insensitive, stripped) between your output and the hidden ground truth on every column except `customer_id` (used as the join key).

Task 1 / Task 2 `schema_target`:

```json theme={null}
{
  "customer_id": "string",
  "name": "string (stripped)",
  "email": "string (lowercase, stripped)",
  "signup_date": "string ISO 8601 or empty",
  "phone": "string E.164 format (+1...) or empty"
}
```

Task 3 `schema_target`:

```json theme={null}
{
  "customer_id": "string",
  "email": "string (lowercase, canonical from Salesforce)",
  "phone": "string (E.164, prefer Web Leads when available)"
}
```

> [!WARNING]
>
> A column missing entirely from your final DataFrame causes the grader to return a score of `0.01` immediately, regardless of how correct your other columns are. Always check that your output contains every key in `schema_target`.

**available\_sources** `List[string]` *required*

The list of DataFrame names currently registered in the environment session. This list grows as you create new sources via `EXECUTE_SQL` (writes to `output_table`) or `MERGE_SOURCES` (writes to `output_table`, typically `"merged_output"`). All source names in this list are valid values for the `source`, `source2`, and `final_source` action fields.

```python theme={null}
# After reset for Task 2:
obs.available_sources  # ["web_forms", "legacy_db"]

# After EXECUTE_SQL with output_table="merged_output":
obs.available_sources  # ["web_forms", "legacy_db", "merged_output"]
```

**current\_view** `string` *required*

A Markdown-formatted table preview of the most recently viewed or modified DataFrame. Updated after `VIEW_SOURCE`, `STANDARDIZE_COLUMN`, `HANDLE_MISSING`, `DEDUPLICATE`, `MERGE_SOURCES`, and `EXECUTE_SQL`. Shows the first 3 rows of the target source.

```
| customer_id | name     | email                | signup_date | phone       |
|-------------|----------|----------------------|-------------|-------------|
| CUST_1001   | John Doe | JOHN.DOE@GMAIL.COM   | 2023/05/15  | 15551234567 |
| CUST_1002   |   Jane   | jane@example.com     | ??/??/????  | None        |
| CUST_1003   | BOB SMITH| BOB@PROMO-ALERTS.NET | 1970-01-01  | +00000000000|
```

Use `current_view` to visually confirm that your transformations are having the expected effect before continuing to the next step. After `POST /reset`, this field contains `"Select a source to view."` as a placeholder.

**data\_quality\_report** `string | null`

A per-column quality summary populated only after a successful `PROFILE_SOURCE` action. Each line follows the format `- **<column>**: type=<dtype>, nulls=<count>`. For all other action types this field is an empty string (not `null`) in the server response, though the Pydantic field is declared `Optional[str]`.

Example output after `PROFILE_SOURCE` on `web_forms`:

```
- **customer_id**: type=object, nulls=0
- **name**: type=object, nulls=2
- **email**: type=object, nulls=9
- **signup_date**: type=object, nulls=8
- **phone**: type=object, nulls=11
```

> [!TIP]
>
> Always run `PROFILE_SOURCE` as your first action after `reset`. The null counts tell you exactly which columns need `HANDLE_MISSING` and give you an early `+0.02` reward.

**last\_action\_feedback** `string` *required*

Always present. Contains a human-readable summary of the outcome of the most recent action. On success it describes what was done (e.g., `"Standardized web_forms.email using LOWERCASE_STRIP"`). On failure it begins with the prefix `"Error: "` followed by the exception message.

| Scenario | Example value |
| - | - |
| Successful profiling | `"Profiled web_forms"` |
| Successful standardize | `"Standardized web_forms.email using StandardizationStrategy.LOWERCASE_STRIP"` |
| Successful dedup | `"Deduplicated web_forms, removed 12 rows."` |
| Successful SQL | `"Executed SQL successfully. Wrote 47 rows to 'web_forms_clean'."` |
| Successful submit | `"Pipeline submitted with final source: web_forms_clean."` |
| Unknown source | `"Error: Source 'typo_source' not found. Available: ['web_forms']"` |
| SQL injection blocked | `"Blocked Action: Only SELECT queries are allowed for security."` |
| Early submit blocked | `"Early submission blocked. You must perform at least 3 cleaning steps..."` |

```python theme={null}
if obs.last_action_feedback.startswith("Error"):
    # Action failed — adjust your next action
    print(f"Action failed: {obs.last_action_feedback}")
```

**conflict\_rules** `Dict[string, string] | null`

Present only in Task 3 (`task_id="t3"`); `null` for Tasks 1 and 2. Maps column names to string labels describing the conflict resolution priority across the three sources (`salesforce`, `web_leads`, `legacy_db`).

Task 3 `conflict_rules`:

```json theme={null}
{
  "email":       "prefer_salesforce",
  "phone":       "prefer_web_leads",
  "customer_id": "prefer_salesforce"
}
```

Use these labels to decide which `ConflictRule` enum value to pass in your `MERGE_SOURCES` actions:

| `conflict_rules` value | Corresponding `ConflictRule` |
| - | - |
| `"prefer_salesforce"` / `"prefer_s1"` | `ConflictRule.PREFER_S1` |
| `"prefer_web_leads"` / `"prefer_s2"` | `ConflictRule.PREFER_S2` |
| `"coalesce"` | `ConflictRule.COALESCE` |

***

## Parsing in Python

```python theme={null}
from models import CRMPipelineAction, PipelineActionType, StandardizationStrategy

# client.step() returns a StepResult; .observation is a CRMPipelineObservation instance
result = client.step(action)
obs = result.observation

# ── Check whether the last action succeeded ──────────────────────────────────
if obs.last_action_feedback.startswith("Error"):
    print(f"Action failed: {obs.last_action_feedback}")
    # Inspect available sources and adjust your next action

# ── Confirm required output columns before submitting ───────────────────────
required_columns = set(obs.schema_target.keys())
print(f"Must produce columns: {required_columns}")
# e.g., {'customer_id', 'name', 'email', 'signup_date', 'phone'}

# ── Track new sources created by SQL or merge operations ─────────────────────
print(f"Sources now available: {obs.available_sources}")
# After EXECUTE_SQL with output_table="merged_output":
# ["web_forms", "legacy_db", "merged_output"]

# ── Parse the quality report after PROFILE_SOURCE ────────────────────────────
if obs.data_quality_report:
    for line in obs.data_quality_report.splitlines():
        print(line)
    # - **email**: type=object, nulls=9
    # - **phone**: type=object, nulls=11

# ── Use conflict rules in Task 3 ─────────────────────────────────────────────
if obs.conflict_rules:
    phone_rule = obs.conflict_rules.get("phone")   # "prefer_web_leads"
    email_rule = obs.conflict_rules.get("email")   # "prefer_salesforce"
    print(f"Phone resolution: {phone_rule}")
    print(f"Email resolution: {email_rule}")

# ── Detect episode completion ─────────────────────────────────────────────────
if obs.done:
    print("Episode complete. Call POST /grader/{episode_id} to retrieve your score.")
```

***

## Full Episode Flow

The following illustrates the full cycle of observations across a Task 1 episode:

```python theme={null}
# 1. Reset — observation has done=false, reward=null, current_view="Select a source to view."
reset_result = client.reset()
obs = reset_result.observation
print(obs.available_sources)          # ["web_forms"]
print(obs.current_task_objective)     # "Normalize web_forms dataset"

# 2. Profile — data_quality_report populated, reward=+0.02
obs = client.step(CRMPipelineAction(
    action_type=PipelineActionType.PROFILE_SOURCE, source="web_forms"
)).observation
print(obs.data_quality_report)
print(obs.reward)                     # 0.02

# 3. Standardize email — current_view updates, reward ∈ [0.01, 0.05]
obs = client.step(CRMPipelineAction(
    action_type=PipelineActionType.STANDARDIZE_COLUMN,
    source="web_forms", column="email",
    standardization_strategy=StandardizationStrategy.LOWERCASE_STRIP
)).observation

# 4. Submit — done=true, reward ∈ [0.00, 0.20]
obs = client.step(CRMPipelineAction(
    action_type=PipelineActionType.SUBMIT_PIPELINE,
    final_source="web_forms"
)).observation
print(obs.done)    # True
print(obs.reward)  # e.g. 0.16
```


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