📝 Update templated files

.github/pull_request_template.md

@@ -6,7 +6,7 @@ List any dependencies that are required for this change.
 
 Fixes #(issue) <!--- Replace `(issue)` with the issue number fixed by this pull request. If this PR does not fix an issue, please remove this line. -->
 
-## Checklist:
+## Checklist
 
 <!---
 This checklist serves as a reminder of a couple of things that ensure your pull request will be merged swiftly.
@@ -18,3 +18,9 @@ This checklist serves as a reminder of a couple of things that ensure your pull
 - [ ] The changes follow the project's style guidelines and introduce no new warnings.
 - [ ] The changes are fully tested and pass the CI checks.
 - [ ] I have reviewed my own code changes.
+
+**If PR contains AI-assisted content:**
+
+- [ ] I have disclosed the use of AI tools in the PR description as per our [AI Usage Guidelines](https://github.com/munich-quantum-toolkit/problemsolver/blob/main/docs/ai_usage.md).
+- [ ] AI-assisted commits include an `Assisted-by: [Model Name] via [Tool Name]` footer.
+- [ ] I confirm that I have personally reviewed and understood all AI-generated content, and accept full responsibility for it.

.github/renovate.json5

@@ -1,7 +1,7 @@
 {
   $schema: "https://docs.renovatebot.com/renovate-schema.json",
   suppressNotifications: ["prEditedNotification"],
-  minimumReleaseAge: '7 days',
+  minimumReleaseAge: "7 days",
   extends: [
     "config:recommended",
     ":gitSignOff",
@@ -14,78 +14,86 @@
     ":prConcurrentLimitNone",
     ":prHourlyLimitNone",
   ],
-  enabledManagers: ["cargo", "github-actions", "npm", "pep621", "pre-commit"],
+  enabledManagers: [
+    "cargo",
+    "github-actions",
+    "npm",
+    "pep621",
+    "pip_requirements",
+    "pre-commit",
+  ],
   lockFileMaintenance: {
     enabled: true,
-    automerge: true
+    automerge: true,
   },
   labels: ["dependencies"],
   schedule: ["every weekend"],
   packageRules: [
     {
       matchManagers: ["cargo"],
       addLabels: ["rust"],
-      commitMessagePrefix: "⬆\uFE0F\uD83E\uDD80"
+      commitMessagePrefix: "⬆\uFE0F\uD83E\uDD80",
     },
     {
       matchManagers: ["github-actions"],
       addLabels: ["github-actions"],
-      commitMessagePrefix: "⬆\uFE0F\uD83D\uDC68\u200D\uD83D\uDCBB"
+      commitMessagePrefix: "⬆\uFE0F\uD83D\uDC68\u200D\uD83D\uDCBB",
     },
     {
       matchManagers: ["npm"],
       addLabels: ["javascript"],
-      commitMessagePrefix: "⬆\uFE0F\uD83D\uDCDC"
+      commitMessagePrefix: "⬆\uFE0F\uD83D\uDCDC",
     },
     {
-      matchManagers: ["pep621"],
+      matchManagers: ["pep621", "pip_requirements"],
       addLabels: ["python"],
-      commitMessagePrefix: "⬆\uFE0F\uD83D\uDC0D"
+      commitMessagePrefix: "⬆\uFE0F\uD83D\uDC0D",
     },
     {
       matchManagers: ["pre-commit"],
       addLabels: ["pre-commit"],
       commitMessagePrefix: "⬆\uFE0F\uD83E\uDE9D",
-      versioning: "pep440"
+      versioning: "pep440",
     },
     {
       matchUpdateTypes: ["lockFileMaintenance"],
       commitMessagePrefix: "⬆\uFE0F\uD83D\uDD12\uFE0F",
     },
     {
-      description: "Group and automerge all patch updates",
+      description: "Group and auto-merge all patch updates",
       groupName: "patch updates",
       matchUpdateTypes: ["patch"],
       matchCurrentVersion: "!/^0\.0/",
       commitMessagePrefix: "⬆\uFE0F\uD83E\uDE79",
-      automerge: true
+      automerge: true,
     },
     {
-      description: "Group and automerge all minor updates of stable dependencies (except our own packages)",
+      description: "Group and auto-merge minor updates of stable dependencies",
       groupName: "minor stable updates",
       matchUpdateTypes: ["minor"],
       matchCurrentVersion: "!/^0\./",
       matchPackageNames: [
         "!munich-quantum-toolkit/*",
         "!munich-quantum-software/*",
+        "!nanobind",
       ],
       commitMessagePrefix: "⬆\uFE0F\uD83E\uDE79",
-      automerge: true
+      automerge: true,
     },
     {
-      description: 'Disable minimum release age checks for our own GitHub Actions',
-      matchManagers: ['github-actions'],
+      description: "Disable minimum release age checks for our own GitHub Actions",
+      matchManagers: ["github-actions"],
       matchPackageNames: [
-        'munich-quantum-toolkit/*',
-        'munich-quantum-software/*',
+        "munich-quantum-toolkit/*",
+        "munich-quantum-software/*",
       ],
       minimumReleaseAge: null,
     },
     {
-      description: 'Disable minimum release age checks for our own Python packages',
-      matchDatasources: ['pypi'],
-      matchPackageNames: ['mqt*'],
+      description: "Disable minimum release age checks for our own Python packages",
+      matchDatasources: ["pypi"],
+      matchPackageNames: ["mqt*"],
       minimumReleaseAge: null,
-    }
-  ]
+    },
+  ],
 }

AGENTS.md

@@ -0,0 +1,64 @@
+<!--- This file has been generated from an external template. Please do not modify it directly. -->
+<!--- Changes should be contributed to https://github.com/munich-quantum-toolkit/templates. -->
+
+# MQT ProblemSolver
+
+## Python
+
+- Install package: `uv sync`
+- Run tests: `uv run pytest`
+- Nox test shortcuts: `uvx nox -s tests`, `uvx nox -s minimums`
+- Python 3.14 variants: `uvx nox -s tests-3.14`, `uvx nox -s minimums-3.14`
+
+## Documentation
+
+- Sources: `docs/`
+- Build docs locally: `uvx nox --non-interactive -s docs`
+- Link check: `uvx nox -s docs -- -b linkcheck`
+
+## Tech Stack
+
+### General
+
+- `prek` for pre-commit hooks
+
+### Python
+
+- Python 3.10+
+- `uv` for installation, packaging, and tooling
+- `ruff` for formatting/linting (configured in `pyproject.toml`)
+- `ty` for type checking
+- `pytest` for unit tests (located in `test/python/`)
+- `nox` for task orchestration (tests, linting, docs)
+
+### Documentation
+
+- `sphinx`
+- MyST (Markdown)
+- Furo theme
+
+## Development Guidelines
+
+### General
+
+- MUST run `uvx nox -s lint` after every batch of changes.
+  This runs the full `prek` hook set from `.pre-commit-config.yaml` (including `ruff`, `typos`, `ty`, formatting, and metadata checks).
+  All hooks must pass before submitting.
+- MUST add or update tests for every code change, even if not explicitly requested.
+- MUST follow existing code style by checking neighboring files for patterns.
+- MUST include a commit footer attribution in the form `Assisted-by: [Model Name] via [Tool Name]` (example: `Assisted-by: Claude Sonnet 4.6 via GitHub Copilot`) if AI tools are used to prepare a commit.
+- NEVER modify files that start with "This file has been generated from an external template. Please do not modify it directly."
+  These files are managed by [the MQT templates action](https://github.com/munich-quantum-toolkit/templates) and changes will be overwritten.
+- PREFER running targeted tests over the full test suite during development.
+
+### Python
+
+- MUST use Google-style docstrings
+- PREFER running a single Python version over the full test suite during development.
+- PREFER fixing reported warnings over suppressing them (e.g., with `# noqa` comments for ruff); only add ignore rules when necessary and document why.
+- PREFER fixing typing issues reported by `ty` before adding suppression comments (`# ty: ignore[code]`); suppressions are sometimes necessary for incompletely typed libraries (e.g., Qiskit).
+
+## Self-Review Checklist
+
+- Did `uvx nox -s lint` pass without errors?
+- Are all changes covered by at least one automated test?

docs/ai_usage.md

@@ -0,0 +1,113 @@
+<!--- This file has been generated from an external template. Please do not modify it directly. -->
+<!--- Changes should be contributed to https://github.com/munich-quantum-toolkit/templates. -->
+
+# AI Usage Guidelines
+
+We acknowledge that AI tools (Large Language Models, code completion engines like GitHub Copilot, etc.) have become helpful assistants for many developers.
+We allow the use of these tools to assist with contributions, provided that their use is transparent, responsible, and that a **human remains in the loop** at all times.
+
+This guide outlines our policy on AI-assisted contributions to ensure code quality, maintainability, and legal compliance.
+
+## Core Principles
+
+### 1. You are Responsible
+
+**You are responsible for every line of code you submit.**
+
+Regardless of whether code was written by you or generated by an AI tool, you are the author and are fully accountable for the contribution. You must:
+
+- Fully understand the code you are submitting.
+- Be able to explain the reasoning behind the code and how it interacts with the rest of the codebase.
+- Verify that the code is correct, efficient, and follows our coding standards.
+
+**Do not blindly copy-paste AI-generated code.** If you cannot explain it, do not submit it.
+
+### 2. Human in the Loop
+
+> **Autonomous contributions from AI agents are not allowed.**
+
+When using AI tools, you must be the driver.
+The AI is the assistant.
+
+- **Review:** You must read and review all AI-generated code or text before submitting it.
+- **Edit:** AI-generated code often requires significant editing to meet project standards and correctness.
+- **Verify:** Ensure the code actually solves the problem and doesn't introduce subtle bugs or security vulnerabilities.
+
+### 3. Communication
+
+**Do not use AI tools to generate issue descriptions, pull request comments, or code reviews.**
+
+We value your personal input and communication.
+LLMs are notoriously unreliable and can produce "smart-sounding" but incorrect or irrelevant claims ("hallucinations").
+Phrase your communications in your own words.
+It is more important that we can follow your reasoning than that the text sounds "perfect".
+
+### 4. Transparency and Disclosure
+
+Transparency helps the community understand the role of these tools and develop best practices.
+
+**We encourage you to disclose any AI assistance.**
+This helps us understand how these tools are being used and identify potential issues.
+You can disclose this information in the following ways:
+
+- **Commit Messages**: Add a trailer to your commit message in the form `Assisted-by: [Model Name] via [Tool Name]` (example: `Assisted-by: Claude Sonnet 4.6 via GitHub Copilot`)
+- **PR Description**: Mention the tool (name and version) and how it was used in the PR description.
+
+### 5. Licensing and Copyright
+
+You are responsible for ensuring that your contribution does not violate any third-party licenses or copyrights.
+
+- **Originality**: Your submission must be your own original work of authorship.
+- **Training Data**: Be aware that some AI tools may generate code that is substantially similar to their training data. You must ensure that you have the right to contribute the generated code under [our license](https://github.com/munich-quantum-toolkit/problemsolver/blob/main/LICENSE.md).
+
+## Extractive Contributions
+
+Processing pull requests and comments for MQT ProblemSolver requires significant maintainer time and energy.
+Sending unreviewed AI output to open-source projects shifts the burden of verifying correctness from the contributor to the maintainer.
+We classify such contributions as "extractive" because they consume more community resources than they provide in value.
+
+Our **golden rule** is that a contribution should be valuable enough to justify the review effort.
+Nadia Eghbal captures this concept in her book _[Working in Public](https://press.stripe.com/working-in-public)_:
+
+> "When attention is being appropriated, producers need to weigh the costs and benefits of the transaction. To assess whether the appropriation of attention is net-positive, it's useful to distinguish between _extractive_ and _non-extractive_ contributions. Extractive contributions are those where the marginal cost of reviewing and merging that contribution is greater than the marginal benefit to the project's producers. In the case of a code contribution, it might be a pull request that's too complex or unwieldy to review, given the potential upside." — Nadia Eghbal
+
+Before AI tools became widespread, open-source project maintainers would often review all changes sent to the project simply because submitting a pull request was a sign of interest from a potential long-term contributor.
+However, AI tools now allow the rapid generation of large volumes of code, which can easily overwhelm maintainers if submitted without careful review.
+Our policy exists to ensure that maintainer time is spent on high-quality interactions rather than debugging AI-generated code.
+
+### Sustainable Open Source
+
+The Munich Quantum Toolkit (MQT) is committed to remaining free, open-source, and permissively licensed.
+We want to build a welcoming community where aspiring quantum software engineers can learn and grow.
+Reviewing contributions is a key part of this mentorship.
+
+However, to keep the project sustainable, we must prioritize non-extractive contributions.
+By thoroughly reviewing and understanding your AI-assisted code before submission, you ensure that your contribution is a net positive for the project.
+This helps us maintain a healthy ecosystem where both the software and its contributors can thrive.
+
+## Prohibited Uses
+
+- **"Good First Issues"**: Do not use AI tools to solve issues labeled as "good first issue". These are intended as learning opportunities for new contributors. Automating them defeats the purpose.
+- **Spam**: Do not use AI to generate low-quality or repetitive comments/reviews ("AI Slop").
+- **Unreviewed Code**: Submitting code that you, as a human, have not reviewed and tested yourself.
+
+## Summary
+
+We want to foster a welcoming community where developers can learn and grow. AI tools can be great for productivity, but they should not replace critical thinking or the learning process.
+If a maintainer judges that a contribution relies too heavily on unverified AI generation or lacks sufficient human understanding ("extractive contribution"), we may request that you revise it or close the PR.
+
+---
+
+Parts of this guide were inspired by or adapted from the contribution guidelines of
+
+- [Astral],
+- [Qiskit],
+- [LLVM], including the sources therein, such as [Fedora Council Policy Proposal: Policy on AI-Assisted Contributions (fetched 2026-03-12)][fedora], which is licensed under the [Creative Commons Attribution 4.0 International License][cca].
+
+with the help of Gemini 3 Pro (Preview). The links above serve as attribution.
+
+[Astral]: https://github.com/astral-sh/uv/blob/c89a78ec085077f6344b0439ddf07fdad7336310/CONTRIBUTING.md
+[Qiskit]: https://github.com/Qiskit/qiskit/blob/cd8701690723d3d9602fac63fe0bd7ea618799be/CONTRIBUTING.md#use-of-ai-tools
+[LLVM]: https://github.com/llvm/llvm-project/blob/9b6391f9c439c9926e8587b7b940e9a1e98a7819/llvm/docs/AIToolPolicy.md
+[fedora]: https://communityblog.fedoraproject.org/council-policy-proposal-policy-on-ai-assisted-contributions/
+[cca]: https://creativecommons.org/licenses/by/4.0/

docs/contributing.md

@@ -55,6 +55,7 @@ Pick the path that fits your time and interests:
 ## Guidelines
 
 Please adhere to the following guidelines to help the project grow sustainably.
+Contributions that do not comply with these guidelines or violate our {doc}`AI Usage Guidelines <ai_usage>` may be rejected without further review.
 
 ### Core Guidelines
 
@@ -71,6 +72,15 @@ Please adhere to the following guidelines to help the project grow sustainably.
 - Follow the project's coding standards and conventions.
 - Be open to feedback and willing to make necessary changes based on code reviews.
 
+### AI-assisted contributions
+
+We acknowledge the utility of AI-based coding assistants (e.g., GitHub Copilot, ChatGPT) in modern software development.
+However, their use requires a high degree of responsibility and transparency to maintain code quality and licensing compliance.
+
+Please carefully read and follow our dedicated {doc}`AI Usage Guidelines <ai_usage>` before submitting any AI-assisted contribution.
+In short: **You are responsible for every line of code you submit**, and a **human must always be in the loop**.
+We require disclosure of AI tool usage in your PR description.
+
 ### Pull Request Workflow
 
 - Create PRs early.
@@ -86,15 +96,28 @@ Please adhere to the following guidelines to help the project grow sustainably.
   Do not close and reopen a new PR.
   Respond to comments to signal that you have addressed the feedback.
   Do not resolve review comments yourself; the reviewer will do so once satisfied.
+- If the reviewer suggested changes with explicit code suggestions as part of the comments, apply these directly using the GitHub UI.
+  This attributes the changes to the reviewer and automatically resolves the respective comments (this is an exception to the rule above).
+  If there are multiple suggestions that you want to apply at once, you can batch them into a single commit.
+  Go to the "Files changed" tab of the PR, and then click "Add suggestion to batch" for each suggestion you want to include.
+  Once you are done selecting suggestions, click "Commit suggestions".
+  Only apply suggestions manually if using the GitHub UI is not feasible.
 - Re-request a review after pushing changes that address feedback.
 - Do not squash commits locally; maintainers typically squash on merge.
   Avoid rebasing or force-pushing before reviews; you may rebase after addressing feedback if desired.
 
 ### Working with CodeRabbit
 
 We use [CodeRabbit](https://www.coderabbit.ai/) for automated code review on pull requests.
+We use this tool to ease the workload on our maintainers and to counteract the trend of sloppy AI-assisted contributions.
+Note that having your PR reviewed by CodeRabbit does **not** count as an AI-assisted contribution for the purpose of the disclosure requirement mentioned above.
+
 To get the most out of it and help the project maintain its high ambitions for code quality, please follow these practices:
 
+- **Review the review**:
+  Do not take CodeRabbit's suggestions as absolute truth.
+  LLMs can be overly defensive and conservative, leading to overcomplicated code.
+  Treat its comments as suggestions: consider them, but feel free to disagree and explain why.
 - **Draft PRs**:
   CodeRabbit runs on every push to non-draft PRs.
   If you are still experimenting, mark your PR as a draft so that the automated review only runs when you are ready for feedback.
@@ -121,13 +144,6 @@ To get the most out of it and help the project maintain its high ambitions for c
   If you want to resume reviews, you can ask CodeRabbit to resume by commenting with {code}`@coderabbitai resume`.
   Note that this will not trigger a review immediately; it will just allow CodeRabbit to perform reviews on the next push or manual trigger.
 
-### Use of AI and LLMs
-
-Contributions may be prepared with the help of AI or LLM tools.
-However, [AI Slop](https://en.wikipedia.org/wiki/AI_slop)—generic, low-value, or clearly machine-generated content that does not meet our standards for clarity, accuracy, or usefulness—is not acceptable.
-Ensure that all text, code, and documentation you submit are accurate, relevant, and consistent with the project's style and guidelines.
-Please be mindful of the maintainers' time and consider the impact of your contributions on the project's long-term success.
-
 ## Get Started 🎉
 
 Ready to contribute?

docs/index.md

@@ -232,6 +232,7 @@ references
 :maxdepth: 1
 
 contributing
+ai_usage
 tooling
 support
 ```