How does Atlas run a specific Polars test?

Atlas runs a specific Polars test by utilizing its `bash` tool to execute `pytest` with the `-k` filter flag. For example, `atlas bash -- pytest my_module/test_data.py::test_lazy_filter -k "test_lazy_filter"` will run only that exact test. This ensures that debugging efforts are focused solely on the failing test, providing minimal output and allowing Polars developers to quickly pinpoint the problem without running the entire test suite.

Can Atlas understand Polars LazyFrame query plans?

Yes, Atlas can understand Polars `LazyFrame` query plans. It achieves this by running `df.lazy().explain()` via its `bash` tool and then using its `read` tool to parse the output. This allows Atlas to identify how predicate pushdown, projection pruning, and other optimizations are applied, helping Polars developers understand the execution flow and pinpoint where a `LazyFrame` chain might be producing incorrect results or performing inefficiently before a `collect()` call.

What Polars formatting tool does Atlas use?

Atlas uses `ruff format` as its default formatter for Polars code. After any code modification made by Atlas's `edit` or `apply_patch` tools, it automatically invokes `ruff format` to ensure that the changes adhere to the project's defined style guidelines. This integration ensures that your Polars codebase remains consistently formatted, reducing friction in code reviews and maintaining high code quality.

How does Atlas ensure I approve code changes in Polars?

Atlas ensures developer approval for all code changes in Polars through a multi-layered safety system. First, it operates with a read-only plan agent that drafts a proposed solution. Only after you approve this plan does it proceed. Crucially, before any file is written to disk, Atlas computes a unified diff of the proposed changes and presents it for your explicit review and approval. This gives you full control over every modification to your Polars code.

Can Atlas help with `uv` for Polars dependencies?

Yes, Atlas can interact with `uv` for managing Polars dependencies. Since Atlas's `bash` tool provides access to a real shell, you can instruct Atlas to run `uv install` or `uv update` commands within your project environment. This allows Atlas to help resolve dependency issues or update your Polars version as specified in your `pyproject.toml`, ensuring your development environment is always correctly configured.

Does Atlas support `assert_frame_equal` in Polars tests?

Atlas fully supports debugging tests that use `assert_frame_equal` in Polars. When `pytest` reports a failure from `assert_frame_equal`, Atlas can read the assertion message and the surrounding code. It then uses its `lsp` tool to work through the `LazyFrame` operations leading to the comparison, helping you understand why the actual and expected `DataFrame`s differ, and guiding you to fix the underlying Polars code logic.

How does Atlas handle large Polars codebases?

Atlas handles large Polars codebases efficiently by indexing code with AST declarations using tree-sitter, rather than relying on blind line windows. This allows for precise semantic and keyword retrieval fused by reciprocal rank fusion, making it highly effective at navigating complex `LazyFrame` structures and finding relevant code sections quickly, even in extensive Polars projects. It also supports local Ollama embeddings to keep your code off third-party servers.

Debug a single failing test in Polars with Atlas in 2026

Atlas helps Polars developers in 2026 efficiently debug a single failing test by running `pytest` in isolation, analyzing `LazyFrame` chains, and applying fixes with `ruff format` for clean code. It integrates directly with your Polars project's `pyproject.toml` and familiar tools like `uv` for dependency management, ensuring a native debugging experience within your terminal.

How Atlas debugs a single failing Polars test

Atlas efficiently debugs a single failing Polars test by leveraging its `bash` tool to execute `pytest` with a specific filter, ensuring only the relevant test runs. This focused approach, critical for complex `LazyFrame` operations, significantly reduces output noise, allowing developers in 2026 to quickly identify the root cause of a failure.

When a Polars test fails, Atlas initiates the debugging process by running `pytest` in isolation. It uses its `bash` tool to execute a command like `pytest path/to/your_test.py::test_specific_failure -k "test_specific_failure"`. This command targets a single test function, preventing the entire test suite from running and providing a concise output focused solely on the problem. After the test execution, Atlas employs its `read` tool to examine the test file and the production code it exercises. For Polars code, this often involves understanding `LazyFrame` transformations and `collect()` calls. The `lsp` tool then becomes invaluable, allowing Atlas to perform `goToDefinition` and `findReferences` operations. This enables Atlas to walk the call graph of the failing test, tracing the data flow through various Polars expressions and identifying the exact point where an unexpected result might be introduced, especially within a long chain of `LazyFrame` operations.

Inspecting Polars LazyFrame code and query plans with Atlas

Atlas provides deep insights into Polars `LazyFrame` code and query plans by using its `read` and `lsp` tools to navigate complex expression APIs. This capability is crucial for Polars developers in 2026, allowing Atlas to interpret `explain()` output and understand how predicate pushdown or projection pruning optimizes data processing.

Understanding the intricate flow of data in Polars `LazyFrame` operations is paramount for effective debugging. Atlas uses its `read` tool to inspect your project's `pyproject.toml` to confirm Polars version pinning and other project configurations. It then leverages the `lsp` tool to navigate through your Polars codebase, specifically focusing on `LazyFrame` chains. Atlas can trace how data is transformed from an initial `scan_csv` or `scan_parquet` through various filters, selections, and aggregations, up to the final `collect()` call that materializes the data. A key feature for Polars is Atlas's ability to interpret the output of `df.lazy().explain()`. By running this command via `bash` and reading its output, Atlas can show you which projections were pruned, where predicate pushdown occurred, and how the query optimizer rearranged operations. This detailed plan analysis helps pinpoint inefficiencies or incorrect logic that might lead to a failing test, especially when dealing with large datasets where performance and correctness are critical.

Applying and reviewing code fixes in Polars with Atlas

Atlas facilitates precise code fixes in Polars by offering `edit` for small adjustments and `apply_patch` for more extensive changes, ensuring developer control over every modification. After applying a fix, Atlas automatically formats the code using `ruff format` and presents a unified diff for approval, streamlining the workflow for Polars developers in 2026.

Once a hypothesis is formed about the failing Polars code, Atlas provides robust tools for applying fixes. For minor adjustments, such as adding a missing `with_columns` or correcting a `filter` condition in a `LazyFrame` chain, the `edit` tool allows for targeted, line-by-line modifications. If the fix spans multiple hunks or requires a more structural change, Atlas can use `apply_patch` to implement a pre-computed patch, ensuring consistency and reducing the risk of errors. After any modification, Atlas automatically invokes `ruff format` to adhere to your project's code style, maintaining code quality without manual intervention. Before writing any changes to disk, Atlas computes a unified diff for every file edit and surfaces it for your approval. This critical safety step ensures that you, the Polars developer, have full visibility and control over every proposed change, allowing you to review, accept, or reject modifications before they are committed to your codebase. Atlas also integrates with `git`, allowing it to read branches, status, and diffs, and can stage and create commits on your behalf after your approval.

Ensuring safety and control in Polars development with Atlas

Atlas prioritizes safety and developer control in Polars projects through permission-gated tool calls and a two-stage agent workflow. Every Atlas tool call, including `bash` commands for `pytest` or `uv`, is permission-gated against allow, ask, and deny rules, providing a robust security layer for Polars developers in 2026.

Atlas is designed with developer safety and control as core principles, especially when interacting with critical Polars codebases. Every tool call, whether it's `bash` to run `pytest`, `edit` to modify a `LazyFrame` definition, or `lsp` to navigate your project, is permission-gated. This means you define explicit allow, ask, or deny rules, ensuring Atlas only performs actions you authorize. The agent operates with a read-only plan agent first, which drafts a detailed plan of action without making any changes. Only after you approve this plan does Atlas switch to a build agent, which then executes the approved steps. Furthermore, before any file is written, Atlas computes a unified diff of the proposed changes and presents it for your explicit approval. This granular control extends to all aspects of Polars development, from modifying `pyproject.toml` to refactoring complex `LazyFrame` expressions. Atlas's ability to snapshot file changes as `git` patches also means that any edits can be easily diffed and rolled back, providing an additional layer of safety and confidence when debugging and fixing Polars code.

Step by step

01Run just the failing Polars test using Atlas's `bash` tool with `pytest -k` to isolate the issue, for example: `atlas bash -- pytest path/to/test_file.py::test_specific_function -k "test_specific_function"`.
02Use Atlas's `read` tool to examine the Polars test file and the `LazyFrame` module it exercises, then employ the `lsp` tool's `goToDefinition` and `findReferences` operations to walk the call path through your Polars expressions.
03Form a hypothesis about the Polars code failure and check it: add temporary logging with Atlas's `edit` tool, or re-run the test with a verbose flag through `bash` to inspect `LazyFrame` states.
04Fix the Polars production code with Atlas's `edit` tool for small changes, or use `apply_patch` if the change spans several hunks in a complex `LazyFrame` definition.
05Re-run the single Polars test with `pytest -k` via `bash` to confirm the fix, then run the full `pytest` suite to ensure no regressions were introduced, especially for `assert_frame_equal` checks.
06Remove any temporary logging you added to the Polars code using Atlas's `edit` tool, ensuring your codebase remains clean.
07Have Atlas format the modified Polars files with `ruff format` and review the unified `git` diff for approval before committing the changes.

Frequently asked questions

How does Atlas run a specific Polars test?: Atlas runs a specific Polars test by utilizing its `bash` tool to execute `pytest` with the `-k` filter flag. For example, `atlas bash -- pytest my_module/test_data.py::test_lazy_filter -k "test_lazy_filter"` will run only that exact test. This ensures that debugging efforts are focused solely on the failing test, providing minimal output and allowing Polars developers to quickly pinpoint the problem without running the entire test suite.
Can Atlas understand Polars LazyFrame query plans?: Yes, Atlas can understand Polars `LazyFrame` query plans. It achieves this by running `df.lazy().explain()` via its `bash` tool and then using its `read` tool to parse the output. This allows Atlas to identify how predicate pushdown, projection pruning, and other optimizations are applied, helping Polars developers understand the execution flow and pinpoint where a `LazyFrame` chain might be producing incorrect results or performing inefficiently before a `collect()` call.
What Polars formatting tool does Atlas use?: Atlas uses `ruff format` as its default formatter for Polars code. After any code modification made by Atlas's `edit` or `apply_patch` tools, it automatically invokes `ruff format` to ensure that the changes adhere to the project's defined style guidelines. This integration ensures that your Polars codebase remains consistently formatted, reducing friction in code reviews and maintaining high code quality.
How does Atlas ensure I approve code changes in Polars?: Atlas ensures developer approval for all code changes in Polars through a multi-layered safety system. First, it operates with a read-only plan agent that drafts a proposed solution. Only after you approve this plan does it proceed. Crucially, before any file is written to disk, Atlas computes a unified diff of the proposed changes and presents it for your explicit review and approval. This gives you full control over every modification to your Polars code.
Can Atlas help with `uv` for Polars dependencies?: Yes, Atlas can interact with `uv` for managing Polars dependencies. Since Atlas's `bash` tool provides access to a real shell, you can instruct Atlas to run `uv install` or `uv update` commands within your project environment. This allows Atlas to help resolve dependency issues or update your Polars version as specified in your `pyproject.toml`, ensuring your development environment is always correctly configured.
Does Atlas support `assert_frame_equal` in Polars tests?: Atlas fully supports debugging tests that use `assert_frame_equal` in Polars. When `pytest` reports a failure from `assert_frame_equal`, Atlas can read the assertion message and the surrounding code. It then uses its `lsp` tool to work through the `LazyFrame` operations leading to the comparison, helping you understand why the actual and expected `DataFrame`s differ, and guiding you to fix the underlying Polars code logic.
How does Atlas handle large Polars codebases?: Atlas handles large Polars codebases efficiently by indexing code with AST declarations using tree-sitter, rather than relying on blind line windows. This allows for precise semantic and keyword retrieval fused by reciprocal rank fusion, making it highly effective at navigating complex `LazyFrame` structures and finding relevant code sections quickly, even in extensive Polars projects. It also supports local Ollama embeddings to keep your code off third-party servers.

Try Atlas in your terminal

The terminal-native AI coding agent. Free core, single binary.

Install Atlas

Related guides

Debug a Single Failing Test with Atlas in 2026

How to debug one failing test with Atlas in 2026: run it in isolation with bash, walk the call graph with the lsp tool, and fix the code, not the assertion.

Atlas for Polars: Terminal-Native AI Coding in 2026

Atlas is a terminal-native AI coding agent for Polars. Build LazyFrame chains, push scan_csv predicates into the reader, and read explain() plans in 2026.

Review a Polars Pull Request with Atlas in 2026

In 2026, Atlas helps Polars developers review pull requests by providing deep context beyond the diff. Catch subtle bugs in LazyFrame chains, validate `pytest (assert_frame_equal)` results, and ensure `ruff format`

Onboard to an Unfamiliar Codebase in Polars with Atlas in 2026

Onboard to unfamiliar Polars codebases in 2026 with Atlas. Build a mental model fast using semantic search, explore subagents, and review diffs for LazyFrame chains and pytest.

Audit a Polars Repository with Parallel Subagents in Atlas, 2026

In 2026, Polars developers use Atlas to sweep entire repositories for code issues. Leverage parallel subagents to audit Polars LazyFrame chains and optimize queries without blowing your context window.

Rename a symbol across the repo in Polars with Atlas in 2026

In 2026, rename Polars functions, classes, or constants across your entire repository with Atlas. Leverage semantic search and lsp for precise refactoring, ensuring no callsite is missed and your pytest suite passes.

Extract a Shared Helper from Duplicated Polars Code with Atlas in 2026

In 2026, Polars developers use Atlas to find and refactor duplicated logic into shared helpers. Leverage semantic search, pytest (assert_frame_equal), and ruff format for robust code.

Run the test suite and triage the failures in Polars with Atlas in 2026

Streamline Polars test triage in 2026 with Atlas. Turn overwhelming `pytest` output into a prioritized list of distinct root causes using `bash`, `grep`, and `todowrite` for efficient debugging.

Browse this resource hub