Build: added initial agent support

AGENTS.md

@@ -0,0 +1,40 @@
+# Agent Guide for PyProximal
+
+## What This Project Is
+PyProximal implements **proximal operators** and **proximal algorithms** for non-smooth, constrained convex optimization. It deliberately does *not* implement linear operators: those come from [PyLops](https://pylops.readthedocs.io) (`pylops.LinearOperator` is a hard dependency, `>= 2.4.0`). Any change that would add a linear-operator implementation here is out of scope by design.
+
+## Where Things Live
+- `pyproximal/`: library code.
+  - `proximal/`: proximal operators (one file per operator family, `UpperCaseCamelCase` filename matching the class).
+  - `projection/`: orthogonal projections onto sets, usually wrapped by the indicator-function proximal operators.
+  - `optimization/`: solvers.
+  - `utils/`: `moreau` and `gradtest_proximal` test helpers, `BilinearOperator`, backend/typing helpers.
+  - `ProxOperator.py`: base class of every proximal operator.
+- `pytests/`: pytest suite.
+- `docs/`, `examples/`, `tutorials/`, `testdata/`: docs, examples, tutorial assets, and test data.
+- `pyproject.toml`: build, test, lint, and packaging config.
+- `Makefile`: preferred entry point for local work.
+
+## Working Here
+- Prefer `make` targets. Use the `*_uv` variants when working in a `uv` environment.
+- Common commands: `make dev-install_uv`, `make tests` or `make tests_uv`, `make lint` or `make lint_uv`, `make typeannot` or `make typeannot_uv`, `make docupdate` or `make docupdate_uv`.
+- Packaging uses `hatchling`; keep build and version settings in `pyproject.toml`.
+
+## Core Design
+- `ProxOperator` implements `prox` and `proxdual` each in terms of the other via the Moreau decomposition, so a subclass needs only one of them; implement both when closed forms exist.
+- Decorate every `prox`/`proxdual` with `@_check_tau`.
+- `grad` on the base class is the gradient of the Moreau envelope, not of the function; pass `hasgrad=True` and override `grad` when a true gradient is known.
+- Solvers exist twice: class-based implementations in `optimization/cls_primal.py` and `cls_primaldual.py` hold the logic; `primal.py` and `primaldual.py` are thin functional wrappers over them. Change behavior in the `cls_*` files.
+- Solvers should support both `numpy` and `cupy` arrays (`get_array_module(x0)`); numba/CUDA paths are optional and selected through an `engine` argument with a runtime fallback (see `proximal/Simplex.py`).
+
+## Style And Tests
+- Follow the `ruff` rules in `pyproject.toml`; compliance is enforced in CI, as is `mypy` in `strict` mode over `pyproximal/`.
+- Keep imports tidy and follow PEP 8 rules.
+- Follow `numpydoc` style for docstrings, with a `Notes` section giving the maths and a reference.
+- Export new operators in the subpackage `__init__.py`: docstring table, star import, and `__all__`, and list them in `docs/source/api/index.rst`.
+- Add or update tests in `pytests/` and examples in `examples/` and/or `tutorials/` when changing behavior or public APIs. Validate a new operator with `moreau` when both prox and dual prox are available, otherwise with ad-hoc edge cases.
+
+## Contribution Flow
+- Use `docs/source/contributing.rst` as the source of truth for longer contribution workflows, and `docs/source/adding.rst` / `docs/source/addingsolver.rst` when implementing a new operator or solver.
+- If functionality changes, update docs and run the relevant tests before handing off.
+- Avoid editing generated artifacts or build output unless the task explicitly requires it.

AIPOLICY.md

@@ -0,0 +1,37 @@
+# PyProximal AI Policy
+
+**Table of Contents**
+
+- [The Short Version](#the-short-version)
+- [The Longer Version](#the-longer-version)
+  - [Philosophy](#philosophy)
+  - [Coding Agents](#coding-agents)
+
+
+## The Short Version
+
+Use AI like you used Google and StackOverflow. Own the final solution like you owned it before.
+
+However, since AI still behaves differently from humans (it is undoubtedly better at certain tasks and worse at others), always acknowledge directly - e.g., let Claude Code author a PR that was strongly driven by it - or indirectly - e.g., explain in the PR where and how AI was used. This helps reviewers and maintainers to pay attention in different ways when reviewing a human-driven code vs an AI-driven code.
+
+## The Longer Version
+
+### Philosophy
+
+PyLops has always been a forward-thinking and inclusive project. At a time when Python was largely regarded as a scripting language for mundane data manipulation and for stitching together HPC software written in lower-level programming languages, we believed that solving large-scale inverse problems efficiently and scalably didn’t necessarily require reaching for those languages. Instead, we focused on achieving greater expressivity, stronger abstractions, and ease of use—all while retaining the power and performance needed for demanding applications.
+
+With the emergence of Coding Agents, the way we approach software development is changing, and we do not intend to be one of those communities that buries its head in the sand and carries on with business as usual. We instead encourage everyone to experiment with AI and Coding Agents and benefit from them in all stages of development.
+
+This however does not mean that we encourage our developers (especially newcomers) to vibe-code complex solutions with little to no control on the physical outcome - lines of code! AI and Coding Agents should be treated as colleagues during pair-coding sessions: they can help in the ideation phase, during development, and in later stages to ensure consistency and act as additional attentive reviewers.
+
+The only **strong recommendation** that we provide to anyone contributing code to PyProximal is to be transparent about their use of AI/Coding Agents. We must recognize that AI still behaves differently from humans - it is undoubtedly better than us in certain tasks but it is still worse in other tasks. If we, reviewers and maintainers, know how a piece of code was generated, we can approach the review process slightly differently whether we review a human-driven code vs an AI-driven code.
+
+### Coding Agents
+
+In order to help our developers, we are committed to provide some of basic ingredients that allow Coding Agent to perform at their best. We aim to be as much as possible vendor-agnostic, and therefore we will provide equivalent versions of *.md* files, skills/commands, etc. that are suitable for one or another Coding Agent.
+
+More specifically, we currently provide:
+
+- ``AGENTS.md / CLAUDE.md``: basic set of instructions that tell coding agents how to work with our specific software project.
+
+🤖🤖 **This Policy was written by humans and polished by AI** 🤖🤖

CLAUDE.md

@@ -0,0 +1,40 @@
+# Agent Guide for PyProximal
+
+## What This Project Is
+PyProximal implements **proximal operators** and **proximal algorithms** for non-smooth, constrained convex optimization. It deliberately does *not* implement linear operators: those come from [PyLops](https://pylops.readthedocs.io) (`pylops.LinearOperator` is a hard dependency, `>= 2.4.0`). Any change that would add a linear-operator implementation here is out of scope by design.
+
+## Where Things Live
+- `pyproximal/`: library code.
+  - `proximal/`: proximal operators (one file per operator family, `UpperCaseCamelCase` filename matching the class).
+  - `projection/`: orthogonal projections onto sets, usually wrapped by the indicator-function proximal operators.
+  - `optimization/`: solvers.
+  - `utils/`: `moreau` and `gradtest_proximal` test helpers, `BilinearOperator`, backend/typing helpers.
+  - `ProxOperator.py`: base class of every proximal operator.
+- `pytests/`: pytest suite.
+- `docs/`, `examples/`, `tutorials/`, `testdata/`: docs, examples, tutorial assets, and test data.
+- `pyproject.toml`: build, test, lint, and packaging config.
+- `Makefile`: preferred entry point for local work.
+
+## Working Here
+- Prefer `make` targets. Use the `*_uv` variants when working in a `uv` environment.
+- Common commands: `make dev-install_uv`, `make tests` or `make tests_uv`, `make lint` or `make lint_uv`, `make typeannot` or `make typeannot_uv`, `make docupdate` or `make docupdate_uv`.
+- Packaging uses `hatchling`; keep build and version settings in `pyproject.toml`.
+
+## Core Design
+- `ProxOperator` implements `prox` and `proxdual` each in terms of the other via the Moreau decomposition, so a subclass needs only one of them; implement both when closed forms exist.
+- Decorate every `prox`/`proxdual` with `@_check_tau`.
+- `grad` on the base class is the gradient of the Moreau envelope, not of the function; pass `hasgrad=True` and override `grad` when a true gradient is known.
+- Solvers exist twice: class-based implementations in `optimization/cls_primal.py` and `cls_primaldual.py` hold the logic; `primal.py` and `primaldual.py` are thin functional wrappers over them. Change behavior in the `cls_*` files.
+- Solvers should support both `numpy` and `cupy` arrays (`get_array_module(x0)`); numba/CUDA paths are optional and selected through an `engine` argument with a runtime fallback (see `proximal/Simplex.py`).
+
+## Style And Tests
+- Follow the `ruff` rules in `pyproject.toml`; compliance is enforced in CI, as is `mypy` in `strict` mode over `pyproximal/`.
+- Keep imports tidy and follow PEP 8 rules.
+- Follow `numpydoc` style for docstrings, with a `Notes` section giving the maths and a reference.
+- Export new operators in the subpackage `__init__.py`: docstring table, star import, and `__all__`, and list them in `docs/source/api/index.rst`.
+- Add or update tests in `pytests/` and examples in `examples/` and/or `tutorials/` when changing behavior or public APIs. Validate a new operator with `moreau` when both prox and dual prox are available, otherwise with ad-hoc edge cases.
+
+## Contribution Flow
+- Use `docs/source/contributing.rst` as the source of truth for longer contribution workflows, and `docs/source/adding.rst` / `docs/source/addingsolver.rst` when implementing a new operator or solver.
+- If functionality changes, update docs and run the relevant tests before handing off.
+- Avoid editing generated artifacts or build output unless the task explicitly requires it.