Python Data Analysis

Atlas can execute Python code in a sandboxed environment for data analysis, statistical computation, and chart generation. The agent writes Python after running SQL queries to produce visualizations and deeper analysis.

Enable

ATLAS_PYTHON_ENABLED=true

Sandbox Backends

Python runs through the same sandbox infrastructure as the explore tool, with the following priority:

Unlike the explore tool, there is no just-bash fallback for Python. If no isolated backend is available, Python execution is rejected with an error.

Available Libraries

The following libraries are available in the sandbox:

• pandas -- DataFrames and data manipulation
• numpy -- Numerical computation
• matplotlib -- Static charts and plots
• plotly -- Interactive charts

The exact set of available libraries depends on the sandbox backend and its Python environment.

Chart Rendering

When Python code generates charts, they appear inline in the chat UI. Two output formats are supported:

Static charts (matplotlib)

The agent calls plt.savefig(chart_path(0)) to save a chart. The sandbox provides a chart_path(n) helper that returns the correct output path for the nth chart. Multiple charts can be generated in a single execution (chart_path(0), chart_path(1), etc.). Charts are returned as base64-encoded PNG images.

Interactive charts (Recharts)

The agent sets a special _atlas_chart variable with structured chart data:

_atlas_chart = {
    "type": "line",           # "line", "bar", or "pie"
    "data": [...],            # Array of data points
    "categoryKey": "month",   # X-axis key
    "valueKeys": ["revenue", "cost"],  # Y-axis keys
}

Recharts output renders natively in the web UI as interactive charts with hover tooltips and legends. Multiple charts can be returned as a list.

Security Model

Python execution is isolated at multiple layers:

1. Import guard -- Defense-in-depth blocking of dangerous modules. Configurable via atlas.config.ts — you can allow specific modules (e.g., requests for sandboxed API calls) or block additional ones. Critical modules (os, subprocess, sys, shutil) can never be unblocked
2. No filesystem writes -- The sandbox environment is read-only
3. No network access -- Outbound connections are blocked by the sandbox
4. No shell access -- os.system(), subprocess.run(), and similar are blocked
5. Timeout enforcement -- Each execution has a configurable time limit

Environment Variables

The sandbox itself is configured via the standard sandbox variables. See Environment Variables and Sandbox Architecture.

How It Works

1. The agent runs a SQL query via executeSQL and gets tabular data
2. The agent writes Python code using the query results as input (passed as a data parameter with columns and rows)
3. Atlas validates the code against blocked imports and builtins
4. The code runs in the sandbox backend with the data available
5. Output (text, tables, or charts) is returned to the agent and displayed in the chat UI

The agent decides when to use Python based on the question -- statistical analysis, trend detection, and visualization requests typically trigger Python execution.

Streaming output

When using the sidecar backend, Python output streams progressively to the chat UI — stdout appears line-by-line as the script runs, and matplotlib charts render inline as soon as savefig is called, rather than waiting for the entire script to complete. Recharts and plotly output is delivered after the script finishes. This uses the sidecar's NDJSON streaming endpoint (/exec-python-stream). If the sidecar does not support the streaming endpoint (older versions), Atlas falls back to the non-streaming sidecar endpoint. Non-sidecar backends (Vercel sandbox, nsjail) always use the standard execution path.

Troubleshooting

"Python execution requires a sandbox"

Cause: No sandbox backend is configured. Unlike the explore tool, Python has no just-bash fallback — it requires an isolated sandbox.

Fix: Set ATLAS_SANDBOX_URL to point to the sidecar (bun run db:up starts one), or configure nsjail or Vercel sandbox. See Sandbox Backends above.

Chart doesn't render in the chat UI

Cause: The Python code generated a chart but used an unsupported output method, or the sandbox timed out before the chart was written.

Fix: Ensure matplotlib charts use plt.savefig(chart_path(0)) — the sandbox provides a chart_path() helper that returns the correct output path. Check ATLAS_PYTHON_TIMEOUT if the script is compute-heavy. Charts rendered in Recharts format appear as interactive components; matplotlib charts appear as static images.

"Blocked import" error

Cause: The Python code tried to import a module on the default blocklist (e.g., subprocess, os, socket). This is a defense-in-depth guard — the sandbox would block these anyway.

Fix: Rewrite the code to avoid blocked modules. For data analysis, use pandas, numpy, matplotlib, and plotly. Some modules like requests can be selectively unblocked via atlas.config.ts for sandboxed environments.

For more, see Troubleshooting.