evylegzhanin/agent-with-sandbox/python-scripts

Python Scripts — Checklist and Recovery

These rules apply whenever you use write_python_file or run_python_file.

Before every Python tool call

1. Tool choice — always write_python_file then run_python_file for each script. Never call run_python_file before write_python_file.
2. Staged file size — keep each write_python_file call to ≤120 lines. If you need more, split across multiple files (for example step1.py, step2.py) and import step1 from step2.
3. Always use `code` — every script is a plain Python string with real newlines. There is no lines field on Python tools.
4. Complete scripts — every call must send a full runnable script for the current step (or active todo). Never send imports-only stubs, pass, or placeholders (..., # TODO).
5. Minimal imports — only what this script uses.
6. Persist intermediates — save DataFrames under /workspace/out as .csv (or .json / .xlsx when needed) and reload in later calls:

``python df.to_csv("/workspace/out/sales.csv", index=False) # later script: df = pd.read_csv("/workspace/out/sales.csv") ` Do **not** use to_parquet / read_parquet` — pyarrow and fastparquet are not installed. Check Workspace state in tool results for paths and shapes already written.

Sandbox environment

Pre-installed Python packages (no pip install):

• pandas, numpy
• openpyxl, xlsxwriter (Excel read/write)
• python-pptx (from pptx import Presentation)
• python-docx (from docx import Document)
• matplotlib, seaborn, Pillow

Not available: pyarrow, fastparquet, scipy, scikit-learn, plotly, requests, and any package not listed above. Parquet files cannot be read or written; use CSV/JSON/Excel instead.

Good example — stage then run

{"filename": "eda_profile.py", "code": "import pandas as pd\n\ndf = pd.read_csv('/workspace/input/data.csv')\nprint('=== SHAPE ===')\nprint(df.shape)\nprint()\nprint('=== DTYPES ===')\nprint(df.dtypes)\n\nfor col in df.select_dtypes(include='object').columns:\n    print(f'{col}: {df[col].nunique()} unique')"}

Then: run_python_file({"script_path": "eda_profile.py"}).

The harness validates the whole script with ast.parse (Python 3.11) and auto-formats with Black.

Do not send

• Import-only stubs — the harness rejects these.
• Scripts with pass or ... as the only body.
• Variable names that shadow keywords (class, def, for, …).
• Placeholder abbreviations (..., # rest of code, # same as above).
• The same rejected payload twice — change the code, or call revise_todo_list.
• Code wrapped in markdown ```python fences inside the JSON argument — use plain Python.

Recovery

Tool errors include a failure class in summary. If the same class appears twice in a row, change approach or call revise_todo_list instead of repeating the same script.

After stub or syntax errors, rewrite with a complete script. Split into smaller staged files when size limits reject the payload.

Validation (harness)

The code string is normalized (markdown fences stripped, line endings normalized), then checked with ast.parse (Python 3.11) before the sandbox runs. Invalid scripts return a syntax error with recovery hints; runtime errors come from sandbox stderr.

Limits

• No shell, no network, no package installation.
• Read inputs from /workspace/input; write persistent outputs under /workspace/out.
• The harness validates syntax (Python 3.11) and auto-formats with Black.
• If run_python_file reports script not found, call write_python_file first.