.env file in the project root. This design keeps the server stateless and fully compatible with containerized deployments on HuggingFace Spaces, Docker Compose, and Kubernetes. This page covers every variable the server and inference script read, how to select task difficulty at reset time, how to point the inference script at any OpenAI-compatible LLM provider, and how the built-in step and submission limits work.
Environment Variables
The table below lists every environment variable recognized by the server and the inference script. Variables marked Yes under Required must be set before the relevant component will function correctly.
Creating your
.env file:
Create a .env file in the project root and populate it with the variables you need. The python-dotenv library loaded by inference.py automatically sources this file at script startup without overriding any variables already present in the shell environment.
.env
Choosing a Task
TheTASK_ID environment variable is the single control knob for task difficulty. You can change the active task between episodes simply by updating the variable and calling /reset again, without restarting the server.
- Shell Export
- Docker Run
- .env File
Task difficulty is cumulative — each harder task is a strict superset of the operations required by the easier ones. If your agent solves
t3 reliably, it will solve t1 and t2 as well.t1): Web Forms Normalization
The agent operates on a single web_forms source. The data contains mixed-case email addresses, phone numbers with inconsistent formatting (parentheses, dashes, dots, extensions), dates in multiple formats (MM/DD/YYYY, natural language, ISO 8601), null values, duplicate entries, and a small number of bot-injected rows identifiable by customer_id = '???' or email LIKE '%bot%'. The agent must profile the data, apply column standardizations, deduplicate by email, filter outliers with EXECUTE_SQL, and submit a clean web_forms_clean table.
Task 2 — Medium (t2): Legacy DB Deduplication
The agent now handles two sources: web_forms and legacy_db. Both require full standardization before they can be merged. After cleaning each source independently, the agent must UNION ALL them via EXECUTE_SQL into a merged_output table and deduplicate the combined set using EXACT_EMAIL. The challenge here is that legacy_db may use different column naming conventions, requiring the agent to inspect schemas carefully before acting.
Task 3 — Hard (t3): Three-Way Enterprise Merge
The most complex task. The agent standardizes three sources — salesforce, web_leads, and legacy_db — each with different schemas (notably legacy_db uses contact_email and home_phone instead of email and phone). The agent must craft a multi-source EXECUTE_SQL aggregation query that renames columns, filters bots, strips the OLD- prefix from legacy_id values, and resolves duplicate email conflicts using MAX() or GROUP BY semantics. A poorly constructed SQL query that leaves extra rows incurs a -0.15 penalty per surplus row in the grader.
LLM Provider Configuration
The inference script is compatible with any provider that exposes an OpenAI-compatible/v1/chat/completions endpoint. Set API_BASE_URL and MODEL_NAME to point the script at your preferred provider.
inference.py script reads provider configuration from environment variables at startup:
HF_TOKEN is checked first; API_KEY is the fallback. If neither is set, all LLM calls will raise an AuthenticationError and the script will fall back to the deterministic rule-based baseline for every step.
Step Limits and Submission Guards
Two constants govern episode pacing and protect the grader from degenerate submissions.MAX_STEPS_PER_TASK = 15 (set in inference.py)
The episode loop runs for at most 15 steps per task before forcibly terminating the episode. This budget is sufficient for the most complex Task 3 multi-source pipeline (which the deterministic baseline solves in 7–8 steps) while preventing runaway agents from consuming excessive API quota. If you are writing a custom agent that needs more steps for exploratory strategies, increase this constant directly in your copy of inference.py.
MIN_STEPS_BEFORE_SUBMIT = 3 (enforced by the environment server)
The environment enforces a minimum of 3 data cleaning steps before it accepts a SUBMIT_PIPELINE action. If an agent sends SUBMIT_PIPELINE as step 1 or step 2, the server returns:
-0.15 penalty is applied to the step reward, the episode continues (it is not terminated), and the agent must continue acting. This guard prevents trivially short episodes that would score near zero and skew evaluation metrics.
Reward shaping summary:
openenv.yaml Reference
Theopenenv.yaml file in the repository root is the machine-readable task catalogue consumed by OpenEnv tooling for environment registration and automated evaluation harness configuration. You do not need to edit this file unless you are extending the environment with new tasks.
openenv.yaml