🎨 C++ Version and Documentation

.devcontainer/Dockerfile

@@ -0,0 +1,11 @@
+FROM --platform=x86_64 python:3.11-bookworm
+
+ENV TZ="Europe/Berlin"
+
+RUN apt-get update -y && \
+    apt-get autoremove -y
+RUN apt-get install -y software-properties-common bash-completion cmake build-essential iputils-ping rsync p7zip-full libuv1-dev git nlohmann-json3-dev librabbitmq-dev libboost-dev libgtest-dev pybind11-dev libgmock-dev
+
+WORKDIR /home
+
+CMD ["bash"]

.devcontainer/devcontainer.json

@@ -0,0 +1,9 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/debian
+{
+  "name": "MQSS Client Development",
+  // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
+  "build": {
+    "dockerfile": "Dockerfile"
+  }
+}

.github/contributing.md

@@ -0,0 +1,116 @@
+# Contributing {#contributing}
+
+<!-- [DOXYGEN] -->
+
+Thank you for your interest in contributing to **MQSS Client**. We value contributions from people
+with all levels of experience.
+
+We use GitHub to [host code](https://github.com/Munich-Quantum-Software-Stack/MQSS Client), to
+[track issues and feature requests][issues], as well as accept [pull
+requests](https://github.com/Munich-Quantum-Software-Stack/MQSS Client/pulls). See
+<https://docs.github.com/en/get-started/quickstart> for a general introduction to working with
+GitHub and contributing to projects.
+
+## Types of Contributions {#types-of-contributions}
+
+Pick the path that fits your time and interests:
+
+- 🐛 Report bugs:
+
+  Use the _🐛 Bug report_ template at
+  <https://github.com/Munich-Quantum-Software-Stack/MQSS-Client/issues>. Include steps to reproduce,
+  expected vs. actual behavior, environment, and a minimal example.
+
+- 🛠️ Fix bugs:
+
+  Browse [issues][issues], especially those labeled "bug", "help wanted", or "good first issue".
+  Open a draft PR early to get feedback.
+
+- 💡 Propose features:
+
+  Use the _✨ Feature request_ template at
+  <https://github.com/Munich-Quantum-Software-Stack/MQSS-Client/issues>. Describe the motivation,
+  alternatives considered, and (optionally) a small API sketch.
+
+- ✨ Implement features:
+
+  Pick items labeled "feature" or "enhancement". Coordinate in the issue first if the change is
+  substantial; start with a draft PR.
+
+- 📝 Improve documentation:
+
+  Add or refine docstrings, tutorials, and examples; fix typos; clarify explanations. Small
+  documentation-only PRs are very welcome.
+
+- ⚡️ Performance and reliability:
+
+  Profile hot paths, add benchmarks, reduce allocations, deflake tests, and improve error messages.
+
+- 📦 Packaging and tooling:
+
+  Improve build configuration, type hints/stubs, CI workflows, and platform wheels. Incremental
+  tooling fixes have a big impact.
+
+- 🙌 Community support:
+
+  Triage issues, reproduce reports, and answer questions in Discussions:
+  <https://github.com/Munich-Quantum-Software-Stack/MQSS-Client/discussions>.
+
+## Guidelines {#guidelines}
+
+Please adhere to the following guidelines to help the project grow sustainably. Contributions that
+do not comply with these guidelines or violate our [AI Usage Guidelines][ai_usage] may be rejected
+without further review.
+
+### Core Guidelines {#core-guidelines}
+
+- ["Commit early and push often"](https://www.worklytics.co/blog/commit-early-push-often).
+- Write meaningful commit messages, preferably using [gitmoji](https://gitmoji.dev) for additional
+  context.
+- Focus on a single feature or bug at a time and only touch relevant files. Split multiple features
+  into separate contributions.
+- Add tests for new features to ensure they work as intended.
+- Document new features. For user-facing changes, add a changelog entry; for breaking changes,
+  update the upgrade guide.
+- Add tests for bug fixes to demonstrate the fix.
+- Document your code thoroughly and ensure it is readable.
+- Keep your code clean by removing debug statements, leftover comments, and unrelated code.
+- Check your code for style and linting errors before committing.
+- 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 {#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 [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 {#pull-request-workflow}
+
+- Create PRs early. Work-in-progress PRs are welcome; mark them as drafts on GitHub.
+- Use a clear title, reference related issues by number, and describe the changes. Follow the PR
+  template; only omit the issue reference if not applicable.
+- CI runs on all supported platforms and Python versions to build, test, format, and lint. All
+  checks must pass before merging.
+- When ready, convert the draft to a regular PR and request a review from a maintainer. If unsure,
+  ask in PR comments. If you are a first-time contributor, mention a maintainer in a comment to
+  request a review.
+- If your PR gets a "Changes requested" review, address the feedback and push updates to the same
+  branch. 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.
+
+<!-- [DOXYGEN] -->

.pre-commit-config.yaml

@@ -60,19 +60,3 @@ repos:
       # Run the formatter.
       - id: ruff-format
         types_or: [python, pyi]
-
-  - repo: local
-    hooks:
-      - id: isort
-        name: isort
-        entry: uv run isort mqss_client/ test/
-        language: system
-        always_run: true
-        pass_filenames: false
-
-      - id: mypy
-        name: mypy
-        entry: uv run python -m mypy mqss_client/ test/
-        language: system
-        always_run: true
-        pass_filenames: false

CMakeLists.txt

@@ -0,0 +1,63 @@
+# ------------------------------------------------------------------------------
+# Copyright 2024 Munich Quantum Software Stack Project
+#
+# Licensed under the Apache License, Version 2.0 with LLVM Exceptions (the
+# "License"); you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# https://github.com/Munich-Quantum-Software-Stack/QDMI-Devices/blob/develop/LICENSE
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations under
+# the License.
+#
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+# ------------------------------------------------------------------------------
+
+# set required cmake version
+cmake_minimum_required(VERSION 3.19...3.30)
+
+project(
+  MQSS-Client
+  VERSION 0.1
+  DESCRIPTION "MQSS Client"
+  LANGUAGES CXX)
+
+# Generate compile_commands.json to make it easier to work with clang based
+# tools
+set(CMAKE_EXPORT_COMPILE_COMMANDS
+    ON
+    CACHE BOOL "Export compile commands" FORCE)
+
+option(BUILD_UNIT_TESTS "Build the unit tests" ON)
+option(ENABLE_COVERAGE "Enabling coverage" ON)
+
+list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
+
+if(ENABLE_COVERAGE)
+  set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} --coverage -O0 -g")
+  set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} --coverage -O0 -g")
+endif()
+
+
+set(CMAKE_C_STANDARD 11)
+set(CMAKE_C_STANDARD_REQUIRED True)
+set(CMAKE_C_EXTENSIONS OFF)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+include(cmake/ExternalDependencies.cmake)
+
+add_subdirectory(src)
+
+if(BUILD_TESTS)
+  add_subdirectory(tests)
+endif()
+
+if(BUILD_DOCUMENTATION)
+  add_subdirectory(docs)
+endif()

README.md

@@ -1,21 +1,100 @@
-## Installation
+<!----------------------------------------------------------------------------
+Copyright 2026 Munich Quantum Software Stack Project
 
-```bash
-pip install mqss-client
-```
+Licensed under the Apache License, Version 2.0 with LLVM Exceptions (the
+"License"); you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
 
-## Usage
+https://github.com/Munich-Quantum-Software-Stack/MQSS-Client/blob/develop/LICENSE
 
-```python
-from mqss_client import MQSSClient
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+License for the specific language governing permissions and limitations under
+the License.
 
-URL = "<mqp-api-url>"
-TOKEN = "<your-mqp-token>"
+SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+-------------------------------------------------------------------------- -->
 
-# create a client instance
-client = MQSSClient(token=TOKEN, url=URL)
-```
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Munich-Quantum-Software-Stack/QDMI/develop/docs/_static/mqss_logo_dark.svg" width="20%">
+    <img src="https://raw.githubusercontent.com/Munich-Quantum-Software-Stack/QDMI/develop/docs/_static/mqss_logo.svg" width="20%">
+  </picture>
+</p>
 
-## Changelog
+# MQSS Client
 
-See the [CHANGELOG](CHANGELOG.md) for details on changes in each version.
+<p align="center">
+  <a href="https://munich-quantum-software-stack.github.io/MQSS-Client/index.html">
+  <img style="min-width: 200px !important; width: 30%;" src="https://img.shields.io/badge/documentation-blue?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0NDggNTEyIj48IS0tIUZvbnQgQXdlc29tZSBGcmVlIDYuNi4wIGJ5IEBmb250YXdlc29tZSAtIGh0dHBzOi8vZm9udGF3ZXNvbWUuY29tIExpY2Vuc2UgLSBodHRwczovL2ZvbnRhd2Vzb21lLmNvbS9saWNlbnNlL2ZyZWUgQ29weXJpZ2h0IDIwMjQgRm9udGljb25zLCBJbmMuLS0+PHBhdGggZmlsbD0iI2ZmZmZmZiIgZD0iTTk2IDBDNDMgMCAwIDQzIDAgOTZMMCA0MTZjMCA1MyA0MyA5NiA5NiA5NmwyODggMCAzMiAwYzE3LjcgMCAzMi0xNC4zIDMyLTMycy0xNC4zLTMyLTMyLTMybDAtNjRjMTcuNyAwIDMyLTE0LjMgMzItMzJsMC0zMjBjMC0xNy43LTE0LjMtMzItMzItMzJMMzg0IDAgOTYgMHptMCAzODRsMjU2IDAgMCA2NEw5NiA0NDhjLTE3LjcgMC0zMi0xNC4zLTMyLTMyczE0LjMtMzIgMzItMzJ6bTMyLTI0MGMwLTguOCA3LjItMTYgMTYtMTZsMTkyIDBjOC44IDAgMTYgNy4yIDE2IDE2cy03LjIgMTYtMTYgMTZsLTE5MiAwYy04LjggMC0xNi03LjItMTYtMTZ6bTE2IDQ4bDE5MiAwYzguOCAwIDE2IDcuMiAxNiAxNnMtNy4yIDE2LTE2IDE2bC0xOTIgMGMtOC44IDAtMTYtNy4yLTE2LTE2czcuMi0xNiAxNi0xNnoiLz48L3N2Zz4=" alt="Documentation" />
+  </a>
+</p>
+<!-- [DOXYGEN MAIN] -->
+
+The **MQSS Client** is a unifying, context-aware access layer and programming library that separates
+programming interfaces from the underlying compiler and runtime stacks. The **MQSS Client** is
+integrated into the _Munich Quantum Software Stack (MQSS)_ to pass quantum jobs to the underlying
+compiler infrastructure and query the properties of available quantum resources. It supports
+multiple programming models, such as gate-based circuits and Hamiltonians. The **MQSS Client**
+serves as an abstract layer between programming interfaces and the underlying compiler
+infrastructure.
+
+<!-- [DOXYGEN MAIN] -->
+
+## FAQ
+
+<!-- [DOXYGEN FAQ] -->
+
+### What is MQSS?
+
+_MQSS_ stands for _Munich Quantum Software Stack_ and is a project of the _Munich Quantum Valley_
+initiative. It is jointly developed by the _Munich Quantum Valley (MQV) gGmbH_, _Leibniz
+Supercomputing Centre (LRZ)_, the _Chair for Design Automation (CDA)_, and the _Chair of Computer
+Architecture and Parallel Systems (CAPS)_ at TUM. It provides a comprehensive compilation and
+runtime infrastructure for on-premise and remote quantum devices, support for modern compilation and
+optimization techniques, and enables both current and future high-level abstractions for quantum
+programming. This stack is designed to be capable of deployment in a variety of scenarios via
+flexible configuration options. This includes stand-alone scenarios for individual systems, cloud
+access to a variety of devices, as well as tight integration into HPC environments supporting
+quantum acceleration. Concrete instances of the _MQSS_ are deployed at the LRZ and MQV gGmbH,
+providing unified access to all of their quantum devices through multiple compatible access paths.
+This includes a web portal, command line access via web credentials, as well as the option for
+hybrid access with tight integration with HPC systems.It facilitates the connection between
+end-users and quantum computing platforms by its integration within HPC infrastructures, such as
+those found at the LRZ.
+
+### What is the MQSS Client?
+
+The **MQSS Client** acts as an abstraction layer for the front-end programming interfaces of _MQSS_.
+Its purpose is to provide a unified interface for communication with the underlying middle-end.
+
+### Where is the code?
+
+The code is publicly available and hosted on GitHub at
+[github.com/Munich-Quantum-Software-Stack/MQSS-Client](https://github.com/Munich-Quantum-Software-Stack/MQSS-Client).
+
+### Under which license is MQSS Client released?
+
+**MQSS Client** is released under the Apache License v2.0 with LLVM Exceptions. See
+[LICENSE](https://github.com/Munich-Quantum-Software-Stack/MQSS-Client/blob/develop/LICENSE.md) for
+more information. Any contribution to the project is assumed to be under the same license.
+
+### In which languages ​​can the MQSS Client be used?
+
+We use C++ to write the core of **MQSS Client**. With the provided Python bindings and C-API, **MQSS
+Client** can be used with Python and C-based applications.
+
+<!-- [DOXYGEN FAQ] -->
+
+## 📬 Contact
+
+The development of this project is led by the QCT department at the LRZ and the QSI department at
+MQV gGmbH. You can also always reach us at
+[mqss@munich-quantum-valley.de](mailto:mqss@munich-quantum-valley.de).
+
+Please try to use the publicly accessible GitHub channels
+([issues](https://github.com/Munich-Quantum-Software-Stack/MQSS-Client/issues),
+[discussions](https://github.com/Munich-Quantum-Software-Stack/MQSS-Client/discussions),
+[pull requests](https://github.com/Munich-Quantum-Software-Stack/MQSS-Client/pulls)) to allow for a
+transparent and open discussion as much as possible.