Skip to content

Introducing AGENTS.md#2233

Open
napetrov wants to merge 5 commits intoIntelPython:masterfrom
napetrov:dev/napetrov_agents
Open

Introducing AGENTS.md#2233
napetrov wants to merge 5 commits intoIntelPython:masterfrom
napetrov:dev/napetrov_agents

Conversation

@napetrov
Copy link

@napetrov napetrov commented Jan 24, 2026

This PR introducing initial version of AGENTS.md and instructions for copilot

  • Have you provided a meaningful PR description?
  • If this PR is a work in progress, are you opening the PR as a draft?

@coveralls
Copy link
Collaborator

coveralls commented Jan 24, 2026

Coverage Status

coverage: 86.248%. remained the same
when pulling 66e3e75 on napetrov:dev/napetrov_agents
into ce41a87 on IntelPython:master.

@napetrov napetrov marked this pull request as ready for review February 2, 2026 05:51
@napetrov napetrov requested a review from Copilot February 2, 2026 05:51
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR introduces comprehensive AI agent documentation (AGENTS.md files) across the dpctl repository to guide AI assistants in understanding the codebase structure, conventions, and patterns. It also adds corresponding GitHub Copilot instruction files to enforce these patterns during code review and generation.

Changes:

  • Added AGENTS.md files documenting architecture, patterns, and conventions for each major component (core bindings, tensor operations, C++ kernels, memory management, testing, and C API layer)
  • Created GitHub-specific instruction files that reference the AGENTS.md documentation for automated code review guidance
  • Established a root-level AGENTS.md that provides project overview and links to component-specific documentation

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated no comments.

Show a summary per file
File Description
AGENTS.md Root documentation providing project overview, architecture diagram, and directory guide
dpctl/AGENTS.md Documentation for core SYCL bindings covering Cython conventions and extension type patterns
dpctl/tensor/AGENTS.md Guide for Array API tensor operations and elementwise wrapper patterns
dpctl/tensor/libtensor/AGENTS.md Documentation for C++ SYCL kernel implementations including functor and factory patterns
dpctl/memory/AGENTS.md USM memory management documentation covering memory types and lifetime rules
dpctl/program/AGENTS.md SYCL kernel compilation documentation and usage patterns
dpctl/utils/AGENTS.md Utility functions documentation focusing on queue validation
dpctl/tests/AGENTS.md Test suite patterns and coverage requirements
libsyclinterface/AGENTS.md C API layer documentation covering naming conventions and memory ownership
.github/instructions/*.instructions.md GitHub Copilot instruction files referencing AGENTS.md for each component

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@napetrov napetrov requested a review from xaleryb February 2, 2026 16:43
@ndgrigorian
Copy link
Collaborator

@napetrov
A few thoughts on this:

  • The parts relevant to dpctl.tensor can be removed even pending the removal of the sub-module, to save us the time of going back to rewrite in ~a month
  • There is a discussion about this topic as it pertains to scipy. They have not yet added this
  • We can look at pytorch, scikit-learn, and pandas for examples as well

In general, the examples seem to lean towards being less verbose about the code itself, and focus more directly on agent behavior/instructions

I will need to test this locally with a few examples, like what's laid out in the SciPy discussion

@napetrov
Copy link
Author

Thanks for the feedback — this makes sense.\n\nI’m narrowing the scope in this PR as follows:\n- remove tensor-specific AGENTS/instructions for now to avoid near-term rework\n- reduce root AGENTS.md verbosity and keep it as a concise entry point\n- keep section-level AGENTS where they provide practical review context\n\nOn alignment with other projects: agreed and reviewed those examples. At the same time, this PR is aimed more at improving AI-assisted review quality (context/invariants) than code generation, so the guidance remains somewhat review-oriented.\n\nAlso, .github/instructions/*.instructions.md are treated as Copilot entry points and should defer to AGENTS.md as the authoritative source, not duplicate full guidance.\n\nHappy to iterate further after local experiments.

|------|---------|
| `conftest.py` | Fixtures and pytest configuration |
| `helper/_helper.py` | `get_queue_or_skip()`, `skip_if_dtype_not_supported()` |
| `elementwise/utils.py` | Dtype and USM type lists for parametrization |
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tests/elementwise will be removed as part of the tensor migration, so its mention can be removed

From `helper/_helper.py`:
```python
get_queue_or_skip() # Create queue or skip test
skip_if_dtype_not_supported() # Skip if device lacks dtype (fp64/fp16)
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

without tensor, this will also not be relevant


**Do not hardcode** - import from `elementwise/utils.py`:
```python
from .utils import _all_dtypes, _usm_types, _no_complex_dtypes
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

also won't exist without tensor

q = get_queue_or_skip()
skip_if_dtype_not_supported(dtype, q)

x = dpt.ones(100, dtype=dtype, sycl_queue=q)
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

uses tensor here, too

@@ -0,0 +1,48 @@
# dpctl/tests/ - Test Suite
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

in general, this should be rewritten without tensor: the focus of the test suite with tensor being removed is on functionality of Python-exposed SYCL objects

## Essential helpers (from `helper/_helper.py`)
```python
get_queue_or_skip() # Create queue or skip
skip_if_dtype_not_supported() # Skip if device lacks dtype
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same as below, dtypes not a concern right now without tensor

Comment on lines +17 to +23
## Dtype/USM lists
Import from `elementwise/utils.py` - do not hardcode.

## Coverage
- All dtypes from `_all_dtypes`
- All USM types: device, shared, host
- Edge cases: empty, scalar, broadcast
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

also not relevant without tensor

## Critical Rules

1. **Device compatibility:** Not all devices support fp64/fp16 - never assume availability
2. **Queue consistency:** Arrays in same operation must share compatible queues
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no arrays without tensor

Comment on lines +28 to +29
### ExecutionPlacementError
Exception raised when arrays are on incompatible queues.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

removed in tensor migration


## Key Functions

### get_execution_queue()
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

removed in tensor migration

@ndgrigorian
Copy link
Collaborator

ndgrigorian commented Mar 19, 2026

@napetrov
Added comments on places where tensor remains present.

In general, I've tested it out similarly to experiments mentioned in the scientific python discussion: I asked it to give me ideas for easy first-time contributions, and it did provide a few good ideas. There were small differences between suggestions with and without AGENTS.md. With AGENTS.md, it referenced the files and some of their specifications, and used that to extrapolate what it perceived as flaws (especially in the test suite).

In both cases, I found that it sometimes took an inordinate amount of time to produce suggestions, so the AGENTS.md are likely not responsible for it.

If the comments above are addressed I'm fine merging this

Remove all references to tests/elementwise/utils.py and dpt.tensor
usage as tests/elementwise will be removed as part of the tensor
migration. Addressed review comments from ndgrigorian.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants