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

# Write a Custom Agent for the CRM Data Pipeline Env

> Build a custom Python agent that interacts with the CRM Pipeline REST API using the typed client library, action models, and observation parsing.

This guide walks you through building a custom Python agent that interacts with the CRM Data Pipeline Environment from scratch. You will use the typed `CRMDataPipelineEnvClient`, the Pydantic action and observation models, and the REST API's step-response cycle to clean, standardize, and merge messy CRM datasets. By the end you will have a working agent capable of scoring `0.99` (the maximum grader award) on Task 1 and the structural vocabulary to tackle Tasks 2 and 3.

## Section 1: The CRMDataPipelineEnvClient

The `client.py` module exports `CRMDataPipelineEnvClient`, a typed wrapper around the environment's REST API. It extends `openenv.core.EnvClient` and handles request serialisation, response parsing, and connection lifecycle for you. You never call the HTTP endpoints directly.

```python theme={null}
from client import CRMDataPipelineEnvClient
from models import CRMPipelineAction, CRMPipelineObservation, PipelineActionType
```

The client exposes two primary methods:

| Method | HTTP call | Returns |
| - | - | - |
| `client.reset()` | `POST /reset` | `StepResult` — initial observation |
| `client.step(action)` | `POST /step` | `StepResult` — updated observation, reward, done flag |

A `StepResult` has three attributes:

```python theme={null}
result.observation   # CRMPipelineObservation — full POMDP state snapshot
result.reward        # float — step reward from the dense heuristic shaper
result.done          # bool — True when the episode has ended
```

The client is used as a context manager via `.sync()` to ensure the underlying connection is closed cleanly at the end of each episode:

```python theme={null}
base_url = os.getenv("OPENENV_BASE_URL", "http://localhost:8080")

with CRMDataPipelineEnvClient(base_url=base_url).sync() as env:
    result = env.reset()
    # ... episode loop ...
```

> [!NOTE]
>
> `CRMDataPipelineEnvClient` includes a graceful `ImportError` fallback for `openenv.core`. If `openenv-core` is not installed, the client stubs out `EnvClient` and `StepResult` so the file still imports. Always install `openenv-core` for production use: `pip install openenv-core`.

## Section 2: The Episode Loop Pattern

Every agent interaction with the environment follows the same canonical pattern: reset → observe → decide → step → repeat until `done=True` or you exceed the step budget.

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

MAX_STEPS = 15
base_url = os.getenv("OPENENV_BASE_URL", "http://localhost:8080")


def run_episode(task_id: str = "t1"):
    os.environ["TASK_ID"] = task_id   # Tell the server which task to load

    with CRMDataPipelineEnvClient(base_url=base_url).sync() as env:
        result = env.reset()
        obs    = result.observation

        print(f"Objective : {obs.current_task_objective}")
        print(f"Sources   : {obs.available_sources}")
        print(f"Schema    : {obs.schema_target}")

        done = False
        step = 0

        while not done and step < MAX_STEPS:
            action = decide_action(obs, step)   # <-- your logic here
            result = env.step(action)
            obs    = result.observation
            done   = result.done
            step  += 1

            print(f"Step {step:02d} | reward={result.reward:.3f} | done={done}")
            print(f"         feedback: {obs.last_action_feedback}")

        print(f"\nEpisode finished in {step} steps. Final reward: {result.reward:.4f}")
        return result.reward
```

> [!TIP]
>
> Set `TASK_ID` as an environment variable **before** calling `reset()`. The server reads it at reset time to load the correct dataset. You cannot change the task mid-episode.

## Section 3: Complete Task 1 Agent

Task 1 (`t1`) presents a single source table named `web_forms` containing customer records with inconsistent email casing, mixed date formats, dirty phone strings, and duplicate rows. The full cleaning sequence is:

1. **Profile** the source to get null counts and type info
2. **Standardize** `email` → lowercase and strip whitespace
3. **Standardize** `signup_date` → ISO-8601 (`YYYY-MM-DD`)
4. **Standardize** `phone` → digits only (`EXTRACT_NUMBERS`) or E.164 format
5. **Deduplicate** by email (exact match)
6. **Drop rows** with null emails
7. **Submit**

```python theme={null}
def t1_agent(obs, step: int) -> CRMPipelineAction:
    source = obs.available_sources[0]   # always "web_forms" for t1

    if step == 0:
        return CRMPipelineAction(
            action_type=PipelineActionType.PROFILE_SOURCE,
            source=source,
        )
    elif step == 1:
        return CRMPipelineAction(
            action_type=PipelineActionType.STANDARDIZE_COLUMN,
            source=source,
            column="email",
            standardization_strategy=StandardizationStrategy.LOWERCASE_STRIP,
        )
    elif step == 2:
        return CRMPipelineAction(
            action_type=PipelineActionType.STANDARDIZE_COLUMN,
            source=source,
            column="signup_date",
            standardization_strategy=StandardizationStrategy.TO_DATETIME_ISO,
        )
    elif step == 3:
        return CRMPipelineAction(
            action_type=PipelineActionType.STANDARDIZE_COLUMN,
            source=source,
            column="phone",
            standardization_strategy=StandardizationStrategy.PHONE_E164,
        )
    elif step == 4:
        return CRMPipelineAction(
            action_type=PipelineActionType.DEDUPLICATE,
            source=source,
            deduplication_strategy=DeduplicationStrategy.EXACT_EMAIL,
        )
    elif step == 5:
        return CRMPipelineAction(
            action_type=PipelineActionType.HANDLE_MISSING,
            source=source,
            column="email",
            missing_strategy=MissingStrategy.DROP_ROW,
        )
    else:
        # Step 6+ — pipeline is clean, submit
        return CRMPipelineAction(
            action_type=PipelineActionType.SUBMIT_PIPELINE,
            final_source=source,
        )
```

Wire it into the episode loop by replacing `decide_action` with `t1_agent`:

```python theme={null}
def run_episode(task_id: str = "t1"):
    os.environ["TASK_ID"] = task_id
    with CRMDataPipelineEnvClient(base_url=base_url).sync() as env:
        result = env.reset()
        obs, done, step = result.observation, False, 0
        while not done and step < MAX_STEPS:
            result = env.step(t1_agent(obs, step))
            obs, done, step = result.observation, result.done, step + 1
        return result.reward

print(run_episode("t1"))   # → 0.99
```

## Section 4: Reading the Observation Effectively

`CRMPipelineObservation` carries every signal your agent needs to decide its next action. Here is how to access each field:

```python theme={null}
# ── Task state ──────────────────────────────────────────────────────────────
obs.current_task_objective   # str: full natural-language instruction
obs.done                     # bool: True once the episode has ended
obs.reward                   # float: reward embedded in the observation

# ── Data inventory ──────────────────────────────────────────────────────────
obs.available_sources        # List[str]: names of tables currently in memory
# e.g. ["web_forms"] for t1, ["web_forms", "legacy_db"] for t2,
#      ["salesforce", "web_leads", "legacy_db"] for t3

# ── Schema requirements ──────────────────────────────────────────────────────
obs.schema_target            # Dict[str, str]: {column_name: expected_dtype}
for col, dtype in obs.schema_target.items():
    print(f"  {col:20s} → {dtype}")
# e.g.
#   customer_id          → str
#   email                → str
#   phone                → str
#   signup_date          → str  (ISO-8601 format expected)

# ── Data preview ────────────────────────────────────────────────────────────
obs.current_view             # str: markdown table of last 3 rows
# Use this to spot remaining dirty values without a full VIEW_SOURCE call.

# ── Quality diagnostics ──────────────────────────────────────────────────────
obs.data_quality_report      # Optional[str]: null % per column after PROFILE_SOURCE
# Only populated after you issue a PROFILE_SOURCE action.
# e.g. "email: 2.5% null | phone: 8.1% null | signup_date: 0.0% null"

# ── Action feedback ───────────────────────────────────────────────────────────
obs.last_action_feedback     # str: human-readable result of your last action
if obs.last_action_feedback.startswith("Error:"):
    print(f"⚠ Action failed: {obs.last_action_feedback}")
else:
    print(f"✓ {obs.last_action_feedback}")

# ── Conflict resolution (Task 3 only) ──────────────────────────────────────
if obs.conflict_rules:
    for col, rule in obs.conflict_rules.items():
        print(f"Column '{col}' conflict rule: {rule}")
# e.g. {"phone": "PREFER_S1", "email": "COALESCE"}
```

### Interpreting feedback strings

The `last_action_feedback` field is the fastest way to understand what the server did. Common patterns:

| Feedback prefix | Meaning |
| - | - |
| `"Successfully standardized..."` | Column transform applied cleanly |
| `"Dropped N duplicate rows..."` | Deduplication completed |
| `"Error: Unknown source..."` | You referenced a table that does not exist yet |
| `"Error: Column not found..."` | Typo in column name or wrong source |
| `"Error: SQL syntax error..."` | Malformed `EXECUTE_SQL` query |
| `"Episode: <uuid> started."` | Returned by the very first `reset()` call |

## Section 5: The Full Action Type Reference

Every action is a `CRMPipelineAction` Pydantic object. Fields not relevant to a given `action_type` should be left as `None` (the default). The server serialises actions via `model_dump_json(exclude_none=True)`.

```python VIEW_SOURCE theme={null}
# Preview the first few rows of a table in markdown format.
# Populates obs.current_view on the next step.
CRMPipelineAction(
    action_type=PipelineActionType.VIEW_SOURCE,
    source="web_forms",
)
```

```python PROFILE_SOURCE theme={null}
# Generate a statistical quality report for the table.
# Populates obs.data_quality_report on the next step.
CRMPipelineAction(
    action_type=PipelineActionType.PROFILE_SOURCE,
    source="legacy_db",
)
```

```python STANDARDIZE_COLUMN theme={null}
# Apply a deterministic transform to one column in place.
# Strategies: LOWERCASE_STRIP, TO_DATETIME_ISO, EXTRACT_NUMBERS, PHONE_E164
CRMPipelineAction(
    action_type=PipelineActionType.STANDARDIZE_COLUMN,
    source="web_forms",
    column="email",
    standardization_strategy=StandardizationStrategy.LOWERCASE_STRIP,
)
```

```python HANDLE_MISSING theme={null}
# Resolve null values in one column.
# Strategies: DROP_ROW, FILL_VALUE, FILL_MEAN, FILL_MODE
# fallback_value is required when missing_strategy=FILL_VALUE.
CRMPipelineAction(
    action_type=PipelineActionType.HANDLE_MISSING,
    source="web_forms",
    column="email",
    missing_strategy=MissingStrategy.DROP_ROW,
)

CRMPipelineAction(
    action_type=PipelineActionType.HANDLE_MISSING,
    source="web_forms",
    column="country",
    missing_strategy=MissingStrategy.FILL_VALUE,
    fallback_value="unknown",
)
```

```python DEDUPLICATE theme={null}
# Strip duplicate rows using a semantic key.
# Strategies: EXACT_EMAIL, FUZZY_NAME_PHONE
CRMPipelineAction(
    action_type=PipelineActionType.DEDUPLICATE,
    source="merged_output",
    deduplication_strategy=DeduplicationStrategy.EXACT_EMAIL,
)
```

```python EXECUTE_SQL theme={null}
# Run a SQL query over in-memory tables (pandasql / DuckDB).
# The result is stored as a new table named output_table.
# DROP and DELETE statements are blocked by the server's SQL sanitiser.
CRMPipelineAction(
    action_type=PipelineActionType.EXECUTE_SQL,
    query="""
        SELECT * FROM web_forms
        WHERE customer_id != '???'
          AND email NOT LIKE '%bot%'
    """,
    output_table="web_forms_clean",
)
```

```python SUBMIT_PIPELINE theme={null}
# End the episode and trigger the grader.
# final_source must be the name of a table currently in memory.
CRMPipelineAction(
    action_type=PipelineActionType.SUBMIT_PIPELINE,
    final_source="merged_output",
)
```

> [!WARNING]
>
> `EXECUTE_SQL` is your most powerful action but also the riskiest. The server blocks `DROP` and `DELETE` keywords, but a `SELECT` that produces zero rows will result in a very low grader score. Always verify your SQL logic on a `VIEW_SOURCE` sample first.

## Section 6: LLM-Based Agent Pattern

You can replace the rule-based `decide_action` function with an LLM call to make the agent generalize across unknown data distributions. The pattern below mirrors what `inference.py` does internally.

```python theme={null}
import json
from openai import OpenAI, RateLimitError
import time

llm = OpenAI(
    api_key=os.getenv("HF_TOKEN") or os.getenv("API_KEY"),
    base_url=os.getenv("API_BASE_URL", "https://router.huggingface.co/v1"),
)

SYSTEM_PROMPT = """You are an expert CRM Data Engineer operating a data pipeline.
Clean, standardize, and merge messy customer datasets.
Respond with EXACTLY one JSON action object — no other text.

Valid action_types: VIEW_SOURCE, PROFILE_SOURCE, STANDARDIZE_COLUMN,
HANDLE_MISSING, DEDUPLICATE, EXECUTE_SQL, SUBMIT_PIPELINE
"""

def build_prompt(obs, step: int) -> str:
    return f"""Task: {obs.current_task_objective}
Available sources: {obs.available_sources}
Target schema: {json.dumps(obs.schema_target)}
Last feedback: {obs.last_action_feedback}
Data quality: {obs.data_quality_report or "Not profiled yet."}
Steps remaining: {15 - step}

Decide your next single action as JSON:"""


def llm_decide(obs, step: int) -> CRMPipelineAction | None:
    prompt = build_prompt(obs, step)
    for attempt in range(3):
        try:
            resp = llm.chat.completions.create(
                model=os.getenv("MODEL_NAME", "Qwen/Qwen2.5-72B-Instruct"),
                messages=[
                    {"role": "system", "content": SYSTEM_PROMPT},
                    {"role": "user",   "content": prompt},
                ],
                response_format={"type": "json_object"},
                temperature=0.2,
            )
            payload = json.loads(resp.choices[0].message.content)
            return CRMPipelineAction(**payload)
        except RateLimitError:
            time.sleep(2 ** attempt)   # 1s, 2s, 4s backoff
        except Exception as e:
            print(f"LLM error (attempt {attempt+1}): {e}")
    return None   # Caller should fall back to a rule-based action
```

Combine with a rule-based fallback for resilience:

```python theme={null}
from inference import build_smart_fallback, validate_action

def decide_action(obs, step: int, task_id: str) -> CRMPipelineAction:
    action = llm_decide(obs, step)
    if action is None:
        print(f"[FALLBACK] step={step}")
        payload = build_smart_fallback(obs, step, task_id)
        action  = validate_action(payload)
    return action
```

## Section 7: Task 2 and Task 3 Patterns

### Task 2 — Two-source merge

Task 2 requires you to clean both `web_forms` and `legacy_db` independently, then union them into a single `merged_output` table and deduplicate.

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

T2_PLAN = [
    # ── Clean web_forms ────────────────────────────────────────────────────
    CRMPipelineAction(action_type=PipelineActionType.STANDARDIZE_COLUMN, source="web_forms", column="email",       standardization_strategy=StandardizationStrategy.LOWERCASE_STRIP),
    CRMPipelineAction(action_type=PipelineActionType.STANDARDIZE_COLUMN, source="web_forms", column="name",        standardization_strategy=StandardizationStrategy.LOWERCASE_STRIP),
    CRMPipelineAction(action_type=PipelineActionType.STANDARDIZE_COLUMN, source="web_forms", column="phone",       standardization_strategy=StandardizationStrategy.EXTRACT_NUMBERS),
    CRMPipelineAction(action_type=PipelineActionType.STANDARDIZE_COLUMN, source="web_forms", column="signup_date", standardization_strategy=StandardizationStrategy.TO_DATETIME_ISO),
    CRMPipelineAction(action_type=PipelineActionType.EXECUTE_SQL,        query="SELECT * FROM web_forms WHERE customer_id != '???' AND email NOT LIKE '%bot%'", output_table="web_forms_clean"),
    # ── Clean legacy_db ────────────────────────────────────────────────────
    CRMPipelineAction(action_type=PipelineActionType.STANDARDIZE_COLUMN, source="legacy_db", column="email",       standardization_strategy=StandardizationStrategy.LOWERCASE_STRIP),
    CRMPipelineAction(action_type=PipelineActionType.STANDARDIZE_COLUMN, source="legacy_db", column="name",        standardization_strategy=StandardizationStrategy.LOWERCASE_STRIP),
    CRMPipelineAction(action_type=PipelineActionType.STANDARDIZE_COLUMN, source="legacy_db", column="phone",       standardization_strategy=StandardizationStrategy.EXTRACT_NUMBERS),
    CRMPipelineAction(action_type=PipelineActionType.STANDARDIZE_COLUMN, source="legacy_db", column="signup_date", standardization_strategy=StandardizationStrategy.TO_DATETIME_ISO),
    CRMPipelineAction(action_type=PipelineActionType.EXECUTE_SQL,        query="SELECT * FROM legacy_db WHERE customer_id != '???' AND email NOT LIKE '%bot%'", output_table="legacy_db_clean"),
    # ── Merge and deduplicate ──────────────────────────────────────────────
    CRMPipelineAction(action_type=PipelineActionType.EXECUTE_SQL,        query="SELECT * FROM web_forms_clean UNION ALL SELECT * FROM legacy_db_clean", output_table="merged_output"),
    CRMPipelineAction(action_type=PipelineActionType.DEDUPLICATE,        source="merged_output", deduplication_strategy=DeduplicationStrategy.EXACT_EMAIL),
    CRMPipelineAction(action_type=PipelineActionType.SUBMIT_PIPELINE,    final_source="merged_output"),
]

def t2_agent(obs, step: int) -> CRMPipelineAction:
    if step < len(T2_PLAN):
        return T2_PLAN[step]
    return CRMPipelineAction(action_type=PipelineActionType.SUBMIT_PIPELINE, final_source="merged_output")
```

### Task 3 — Three-source enterprise merge with conflict rules

Task 3 adds a third source (`salesforce`) and requires you to check `obs.conflict_rules` to understand how the grader expects conflicting column values to be resolved. The legacy\_db source uses different column names (`contact_email`, `home_phone`, `legacy_id`) that must be aliased in SQL.

```python theme={null}
def t3_agent(obs, step: int) -> CRMPipelineAction:
    if step == 0:
        # Inspect conflict rules before writing your merge SQL
        print(f"Conflict rules: {obs.conflict_rules}")

    T3_PLAN = [
        CRMPipelineAction(action_type=PipelineActionType.STANDARDIZE_COLUMN, source="salesforce", column="email",         standardization_strategy=StandardizationStrategy.LOWERCASE_STRIP),
        CRMPipelineAction(action_type=PipelineActionType.STANDARDIZE_COLUMN, source="salesforce", column="phone",         standardization_strategy=StandardizationStrategy.EXTRACT_NUMBERS),
        CRMPipelineAction(action_type=PipelineActionType.STANDARDIZE_COLUMN, source="web_leads",  column="email",         standardization_strategy=StandardizationStrategy.LOWERCASE_STRIP),
        CRMPipelineAction(action_type=PipelineActionType.STANDARDIZE_COLUMN, source="web_leads",  column="phone",         standardization_strategy=StandardizationStrategy.EXTRACT_NUMBERS),
        CRMPipelineAction(action_type=PipelineActionType.STANDARDIZE_COLUMN, source="legacy_db",  column="contact_email", standardization_strategy=StandardizationStrategy.LOWERCASE_STRIP),
        CRMPipelineAction(action_type=PipelineActionType.STANDARDIZE_COLUMN, source="legacy_db",  column="home_phone",    standardization_strategy=StandardizationStrategy.EXTRACT_NUMBERS),
        CRMPipelineAction(
            action_type=PipelineActionType.EXECUTE_SQL,
            query="""
                SELECT MAX(customer_id) AS customer_id, email, MAX(phone) AS phone
                FROM (
                    SELECT customer_id, email, phone FROM salesforce
                        WHERE customer_id != '???' AND email NOT LIKE '%bot%'
                    UNION ALL
                    SELECT customer_id, email, phone FROM web_leads
                        WHERE customer_id IS NOT NULL AND email NOT LIKE '%bot%'
                    UNION ALL
                    SELECT REPLACE(legacy_id, 'OLD-', 'CUST_') AS customer_id,
                           contact_email AS email,
                           home_phone    AS phone
                    FROM legacy_db
                        WHERE legacy_id != '???' AND contact_email NOT LIKE '%bot%'
                )
                GROUP BY email
            """,
            output_table="merged_output",
        ),
        CRMPipelineAction(action_type=PipelineActionType.SUBMIT_PIPELINE, final_source="merged_output"),
    ]

    if step < len(T3_PLAN):
        return T3_PLAN[step]
    return CRMPipelineAction(action_type=PipelineActionType.SUBMIT_PIPELINE, final_source="merged_output")
```

## Section 8: Error Handling

Agents should be defensive. The server is lenient about bad actions (it returns a negative reward and an error feedback string rather than crashing), but your agent needs to recover gracefully.

```python theme={null}
def safe_step(env, action: CRMPipelineAction, fallback: CRMPipelineAction):
    """Try an action; fall back to a safe alternative on server-side error."""
    result = env.step(action)
    if result.observation.last_action_feedback.startswith("Error:"):
        print(f"Action failed: {result.observation.last_action_feedback}")
        result = env.step(fallback)
    return result
```

### Common error patterns and fixes

> [accordion] reward=-0.05 with 'Error:' in feedback
>
> The server rejected your action. This usually means:
>
> * **Wrong source name**: Double-check `obs.available_sources`. SQL-created tables (e.g., `web_forms_clean`) only appear in `available_sources` after the `EXECUTE_SQL` that created them.
> * **Wrong column name**: Use `PROFILE_SOURCE` first to see exact column names. Legacy DB often uses `contact_email` instead of `email`.
> * **Invalid strategy**: Confirm the strategy string exactly matches the enum values in `models.py` (`TO_DATETIME_ISO`, not `ISO_DATE`).
>
> ```python theme={null}
> # Always verify source exists before referencing it
> assert "web_forms_clean" in obs.available_sources, \
>     f"Table not ready. Available: {obs.available_sources}"
> ```

> [accordion] done=False after SUBMIT\_PIPELINE
>
> The server accepted your submission but returned `done=False`. This happens when you call `SUBMIT_PIPELINE` before completing at least 3 meaningful cleaning steps. The server enforces a minimum pipeline depth to prevent trivially submitting raw data.
>
> Check `obs.last_action_feedback` for a hint like `"Pipeline too shallow — apply at least 3 transformations before submitting."` Then continue cleaning before retrying `SUBMIT_PIPELINE`.

> [accordion] EXECUTE\_SQL returns zero rows
>
> Your `WHERE` clause is too restrictive or uses wrong column names. Use `VIEW_SOURCE` after the SQL to inspect the resulting table:
>
> ```python theme={null}
> # After EXECUTE_SQL, view the output to verify
> result = env.step(CRMPipelineAction(
>     action_type=PipelineActionType.VIEW_SOURCE,
>     source="merged_output",
> ))
> print(result.observation.current_view)
> ```
>
> If the view is empty, revise your SQL and run `EXECUTE_SQL` again with a different `output_table` name. Old table names remain valid in memory — you can overwrite them.

> [accordion] Score 0.01 despite correct-looking data
>
> A score of `0.01` is the grader's minimum — it means the grader could not match **any** rows. The most common causes:
>
> * You submitted the wrong `final_source` name (e.g., `web_forms` instead of `merged_output` for t2/t3).
> * Dates are still in `MM/DD/YYYY` format instead of `YYYY-MM-DD` — apply `TO_DATETIME_ISO` before submitting.
> * Phone numbers contain non-digit characters — apply `EXTRACT_NUMBERS` or `PHONE_E164`.
> * `customer_id` values contain `'???'` placeholders — filter them with `EXECUTE_SQL`.


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