intelloptim 0.1.0__tar.gz

intelloptim-0.1.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @mbarbetti

intelloptim-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,29 @@
+name: Bug report
+description: Something does not work as documented
+labels: [bug]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened, and what did you expect?
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal example
+      description: Code that reproduces the problem. Remove tokens and private URLs.
+      render: python
+  - type: input
+    id: version
+    attributes:
+      label: intelloptim version
+      placeholder: "python -c 'import intelloptim; print(intelloptim.__version__)'"
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version and operating system
+    validations:
+      required: true

intelloptim-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/mbarbetti/intelloptim/security/advisories/new
+    about: Please report security problems privately, not in a public issue.

intelloptim-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,14 @@
+name: Feature request
+description: Suggest an improvement
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem would this solve?
+    validations:
+      required: true
+  - type: textarea
+    id: idea
+    attributes:
+      label: What would you like to see?

intelloptim-0.1.0/.github/dependabot.yml

@@ -0,0 +1,21 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns: ["*"]
+    commit-message:
+      prefix: "ci"
+
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      python-dependencies:
+        patterns: ["*"]
+    commit-message:
+      prefix: "build"

intelloptim-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,11 @@
+## What and why
+
+<!-- What changes, and why. Link the issue if there is one. -->
+
+## Checklist
+
+- [ ] The PR title follows Conventional Commits (`feat(scope): ...`, `fix: ...`, `docs: ...`)
+- [ ] Tests added or updated, and `nox` passes locally
+- [ ] `CHANGELOG.md` has an entry under `[Unreleased]` (or the PR is labelled `skip-changelog`)
+- [ ] Public API, docstrings and README updated if behaviour changed
+- [ ] No credentials, tokens or private data in code, tests or logs

intelloptim-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,126 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_call:
+    inputs:
+      full:
+        description: "Run every supported Python version"
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  plan:
+    runs-on: ubuntu-latest
+    outputs:
+      python: ${{ steps.pick.outputs.python }}
+    steps:
+      - id: pick
+        env:
+          FULL: ${{ inputs.full || github.event_name == 'push' }}
+        run: |
+          if [ "$FULL" = "true" ]; then
+            echo 'python=["3.11","3.12","3.13","3.14","3.15"]' >> "$GITHUB_OUTPUT"
+          else
+            echo 'python=["3.11","3.15"]' >> "$GITHUB_OUTPUT"
+          fi
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7
+        with:
+          python-version: "3.12"
+      - run: python -m pip install nox
+      - run: nox -s lint --default-venv-backend virtualenv
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7
+        with:
+          python-version: "3.12"
+      - run: python -m pip install nox
+      - run: nox -s typecheck --default-venv-backend virtualenv
+
+  test:
+    needs: plan
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ${{ fromJSON(needs.plan.outputs.python) }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install nox
+      - run: nox -s "tests-${{ matrix.python }}" --default-venv-backend virtualenv
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7
+        with:
+          python-version: "3.12"
+      - run: python -m pip install nox
+      - run: nox -s build --default-venv-backend virtualenv
+
+  changelog:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: CHANGELOG.md must change unless the PR is labelled skip-changelog
+        if: >-
+          !contains(github.event.pull_request.labels.*.name, 'skip-changelog')
+          && github.actor != 'dependabot[bot]'
+        env:
+          BASE_REF: ${{ github.base_ref }}
+        run: |
+          if ! git diff --name-only "origin/${BASE_REF}...HEAD" | grep -qx CHANGELOG.md; then
+            echo "::error::Add an entry under [Unreleased] in CHANGELOG.md, or label the PR skip-changelog."
+            exit 1
+          fi
+
+  # The only status check that branch protection needs to require.
+  ci-ok:
+    if: always()
+    needs: [plan, lint, typecheck, test, build, changelog]
+    runs-on: ubuntu-latest
+    steps:
+      - env:
+          RESULTS: ${{ join(needs.*.result, ' ') }}
+        run: |
+          echo "job results: $RESULTS"
+          case " $RESULTS " in
+            *" failure "*|*" cancelled "*) exit 1 ;;
+          esac

intelloptim-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,114 @@
+name: Release
+
+# Pushing a tag vX.Y.Z (or vX.Y.ZrcN) from main builds the distributions and
+# publishes them: pre-releases to TestPyPI, final releases to PyPI after the
+# `pypi` environment is approved. No token is stored: PyPI trusts this workflow
+# (Trusted Publishing).
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    outputs:
+      prerelease: ${{ steps.kind.outputs.prerelease }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: The tagged commit must be on main
+        run: |
+          git fetch --no-tags origin main
+          git merge-base --is-ancestor "$GITHUB_SHA" origin/main
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7
+        with:
+          python-version: "3.12"
+      - run: python -m pip install build twine packaging
+      - id: kind
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          echo "prerelease=$(python scripts/release_tools.py prerelease "$TAG")" >> "$GITHUB_OUTPUT"
+          python scripts/release_tools.py notes "$TAG" > /dev/null
+      - run: python -m build --outdir dist
+      - run: twine check --strict dist/*
+      - env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          python scripts/release_tools.py check-dist dist "$TAG"
+          python scripts/release_tools.py check-contents dist
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish-testpypi:
+    needs: build
+    if: needs.build.outputs.prerelease == 'true'
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/project/intelloptim/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    needs: build
+    if: needs.build.outputs.prerelease == 'false'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/intelloptim/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
+
+  github-release:
+    needs: [build, publish-testpypi, publish-pypi]
+    if: >-
+      always() && needs.build.result == 'success'
+      && (needs.publish-testpypi.result == 'success' || needs.publish-pypi.result == 'success')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8
+        with:
+          name: dist
+          path: dist/
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7
+        with:
+          python-version: "3.12"
+      - run: python -m pip install packaging
+      - name: Create the GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+          PRERELEASE: ${{ needs.build.outputs.prerelease }}
+        run: |
+          python scripts/release_tools.py notes "$TAG" > notes.md
+          flag=""
+          if [ "$PRERELEASE" = "true" ]; then flag="--prerelease"; fi
+          gh release create "$TAG" dist/* --title "$TAG" --notes-file notes.md $flag

intelloptim-0.1.0/.github/workflows/scheduled.yml

@@ -0,0 +1,45 @@
+name: Scheduled
+
+on:
+  schedule:
+    - cron: "0 5 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  ci:
+    uses: ./.github/workflows/ci.yml
+    with:
+      full: true
+
+  extras-installable:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.12", "3.13", "3.14", "3.15"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Every extra can still be resolved on this Python
+        run: python -m pip install --dry-run ".[samplers,quantum-ibm]"
+
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7
+        with:
+          python-version: "3.12"
+      - run: python -m pip install ".[samplers,quantum-ibm]" pip-audit
+      - run: pip-audit

intelloptim-0.1.0/.gitignore

@@ -0,0 +1,59 @@
+# GenAI tools
+.claude/
+AGENTS.md
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+.nox/
+*.egg
+.eggs/
+build/
+dist/
+wheels/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.tox/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Virtual envs (we use conda envs outside the repo, but keep these out anyway)
+.venv/
+venv/
+env/
+
+# Local dev
+*.db
+*.db-journal
+*.sqlite
+*.sqlite3
+dev.db*
+
+# OS / editors
+.DS_Store
+.idea/
+.vscode/
+*.swp
+*~
+
+# Frontend
+node_modules/
+frontend/dist/
+frontend/.vite/
+frontend/coverage/
+
+# Docker / runtime
+.env
+.env.local
+*.pid
+
+# Logs
+*.log
+logs/

intelloptim-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,34 @@
+# Hooks for local use: `pre-commit install`. The formatters and the type checker
+# are the ones installed with the `dev` extra (`language: system`), so the
+# versions and the dependencies are the same as in `nox` and in CI.
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+        args: ["--maxkb=512"]
+      - id: check-merge-conflict
+      - id: debug-statements
+
+  - repo: local
+    hooks:
+      - id: black
+        name: black
+        entry: black
+        language: system
+        types: [python]
+      - id: ruff
+        name: ruff
+        entry: ruff check --fix
+        language: system
+        types: [python]
+      - id: mypy
+        name: mypy
+        entry: mypy src/intelloptim
+        language: system
+        pass_filenames: false
+        files: ^src/intelloptim/

intelloptim-0.1.0/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to this project are documented in this file. The format
+follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project
+uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html); while the
+version is below 1.0, minor releases may contain breaking changes.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-30
+
+First public release.
+
+### Added
+
+- Client SDK in `intelloptim.client` (`Client`, `StudyHandle`, `Trial`,
+  `TrialState` and the `errors` module) for an intelloptim server: ask/tell,
+  enqueue, early stopping with `Trial.report` and `Trial.should_prune`
+  (`TrialPruned` ends a pruned trial). `intelloptim.client` and
+  `intelloptim.algorithms` are loaded on first access, so `import intelloptim`
+  stays light.
+- Declarative search spaces (`intelloptim.params`) with float, int and
+  categorical parameters.
+- Sampler and pruner specifications backed by Optuna (Random, TPE, GP, NSGA-II,
+  QMC; Median, Percentile, Threshold, Nop) and the built-in samplers SA and OWG.
+- Quantum policy samplers (Gaussian and mixture variants) with a simulated
+  version and a hardware version, an executor plugin mechanism
+  (`intelloptim.quantum_executors`) and an IBM Runtime executor.
+- `intelloptim-worker evaluator` command, which runs an objective registered with
+  `@intopt.objective` against a server, for example as a SLURM array job. Each
+  worker sends its worker and site ids (`StudyHandle.optimize(...,
+  worker_id=...)`), derived from the SLURM environment.
+- Optional extras: `gp`, `qmc`, `quantum`, `quantum-ibm`, `samplers`.
+
+[Unreleased]: https://github.com/mbarbetti/intelloptim/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/mbarbetti/intelloptim/releases/tag/v0.1.0

intelloptim-0.1.0/CLAUDE.md

@@ -0,0 +1,178 @@
+# intelloptim — project guidance
+
+## What this repo is
+
+The client SDK and the algorithm layer of **intelloptim**, a general black-box
+optimization framework built on Optuna's ask/tell API (an evolution of
+**Hopaas**, Barbetti & Anderlini, 2023,
+[arXiv:2301.05522](https://arxiv.org/abs/2301.05522)). It contains the user-facing
+client, the pure domain types, the wire protocol, and the sampler/pruner
+resolution including the in-repo sampler runtimes. Imported as
+`import intelloptim as intopt`.
+
+Users install it to talk to a running intelloptim server and to write
+objectives. The server and the dashboard are separate projects that depend on
+this package for its domain types, wire schemas, hashing and algorithms.
+
+## Mental map
+
+```
+src/intelloptim/
+  _internal/      wire schemas (incl. TrialState), hashing (study identity),
+                  logging, audit helpers
+  core/           pure domain types — no I/O, only pydantic
+    samplers/       base.py (SamplerKind, rebuild policy, base specs),
+                    optuna.py (Random/TPE/GP/NSGA-II/QMC specs),
+                    builtin.py (SA/OWG specs), quantum.py (quantum policy
+                    specs: Gaus/Mixture, simulated "Sim" and hardware)
+    pruners/        base.py (PrunerKind), optuna.py (Median/Percentile/
+                    Threshold/Nop specs)
+    parameters.py, objective.py
+  algorithms/     spec -> optuna resolvers (samplers.py, pruners.py) and
+                  load_sampler_plugins() entry-point discovery
+    backend/        runtime for non-Optuna samplers (builtin/: sa.py, owg.py;
+                    quantum/: gaus.py, mixture.py, commons/ for the
+                    vendor-neutral policy, learner and executors, qiskit/ for
+                    the only Qiskit code)
+    protocols.py, errors.py, space.py
+  client/         REST/WS SDK (Client, StudyHandle, Trial, errors) — httpx
+  worker/         `intelloptim-worker` CLI (evaluator subcommand, worker and site
+                  identity from the SLURM environment)
+  params.py       public facade over core/parameters (`intopt.params.Float`)
+```
+
+## Hard layering rules
+
+1. **`core/` is pure**: stdlib and pydantic only; no `httpx`, `optuna`, I/O or
+   networking.
+2. **`algorithms/` is the only place Optuna's sampler/pruner classes are
+   imported.** `core/` holds specs; `algorithms/` resolves them.
+3. **`_internal/schemas.py` is the only place wire models are defined.**
+4. **`_internal/hashing.py` output is byte-stable.** Golden tests pin it;
+   changing the hashed payload changes every study id.
+5. **`client/` is the only module that talks to a server over HTTP.**
+6. **Quantum samplers** (`SimQuantumGaus`, `QuantumGaus`, `SimQuantumMixture`,
+   `QuantumMixture`) live in-repo: specs in `core/samplers/quantum.py`, runtime
+   in `algorithms/backend/quantum/`. The `Sim` samplers are ideal; the others
+   run on hardware and are separate kinds on purpose. Specs never carry
+   credentials, and only `algorithms/backend/quantum/qiskit/` imports Qiskit.
+
+## Wire protocol and stability
+
+- The wire models and `API_VERSION` live in `_internal/schemas.py`; the sampler
+  and pruner unions are `SamplerSpec` and `PrunerSpec`. Changing any of them is
+  a versioned event that the server and the dashboard must follow.
+- Study-scoped requests carry `study_id` in the URL and `config_digest` in the
+  body; **409** on mismatch (`ConfigDigestMismatchError`).
+- **503 + `Retry-After`** from `/ask` while a sampler rebuilds
+  (`StudyRebuildingError`). **410** from `/ask` and `/enqueue` when the study is
+  stopped (`StudyStoppedError`). **429** from `/ask` or `/tell` when the quota is
+  exhausted.
+- `POST /studies/{id}/trials/{tid}/should_prune` takes the intermediate values
+  not yet sent and returns `{"should_prune": bool}`; it is not quota-counted.
+- Study identity: `study_id = sha256(study_key, study_name, direction,
+  canonicalized_params, sampler_spec, pruner_spec)`, always computed with
+  `study_identity(study_key, request)`; `study_key` is an opaque per-user or
+  per-group key resolved by the server, never the API token.
+- `trial_id` is an opaque handle; `number` is the position in the study.
+
+## Samplers
+
+To add a **built-in** sampler: add a spec class in `core/samplers/`, add its
+`kind` to `SamplerKind`, add it to the `SamplerSpec` union, and register a
+resolver in `algorithms/samplers.py:_RESOLVERS`. If it is not a thin wrapper
+over an Optuna sampler, put its runtime in `algorithms/backend/`. Pruners follow
+the same pattern.
+
+Built-in samplers must be **stateless**: the server builds a fresh sampler on
+every ask, so anything an in-memory sampler would remember must be rebuilt from
+the study history (with RNGs derived from the seed and trial number) or from a
+model persisted in the study by `rebuild(study)` (see `OWG`, `SA` and the
+quantum samplers).
+
+External packages can override the resolver of an existing kind through the
+`intelloptim.samplers` entry-point group, and add a quantum provider through
+`intelloptim.quantum_executors`.
+
+Ships in-repo: `Random`, `TPE`, `GP`, `NSGA-II`, `QMC` (Optuna-backed; `GP`
+needs the `gp` extra, `QMC` the `qmc` extra), `SA`, `OWG`, and the quantum
+policy samplers (extras `quantum`, `quantum-ibm`). A missing optional package
+raises `SamplerDependencyError` naming the extra to install.
+
+## SDK contract
+
+```python
+import intelloptim as intopt
+with intopt.client.Client(url="...", token=...) as client:
+    study = client.create_study(
+        study_name="...", direction="minimize",
+        sampler_spec=intopt.samplers.TPESamplerSpec(seed=42),
+        parameters=[intopt.params.Float("x", -10, 10)],
+    )
+    study.optimize(my_objective, n_trials=50, catch=Exception)
+    best = study.best_trial
+```
+
+- The search space is declared once, in `create_study(parameters=[...])`.
+  Objectives read the sampled values by name: `trial.sampled_float("x")`,
+  `sampled_int`, `sampled_categorical`. There is no `suggest_*`.
+- `tell(state=COMPLETE)` requires `value`; `PRUNED`/`FAILED` accept `None`.
+- Early stopping: `trial.report(value, step)` buffers locally,
+  `trial.should_prune()` sends the new values, and the objective raises
+  `intopt.client.errors.TrialPruned`, which `optimize` records as `PRUNED`.
+- `create_study` is idempotent and parallel-safe; `best_trial` is `None` until
+  one trial completes. `optimize(n_trials=N)` raises `InsufficientQuotaError`
+  before any call if `N` exceeds the remaining calls.
+
+Client errors: `ConfigDigestMismatchError` (409), `StudyRebuildingError` (503),
+`StudyStoppedError` (410), `MissingTokenError`, `InsufficientQuotaError`,
+`StudyLimitExceededError`.
+
+## Testing
+
+- `tests/unit/` tests pure logic and never imports third-party quantum SDKs; the
+  quantum samplers run against a numpy executor in `tests/support/`.
+  `tests/integration/` (marker `qiskit`) uses real Qiskit and a stubbed IBM
+  runtime. Tests marked `hardware` hit a real device, are opt-in, and must never
+  run in automation.
+- `client/` tests use `httpx.MockTransport`; there is no dependency on a server.
+- Every feature or fix ships with `pytest` tests (happy path and edge cases).
+
+## Style
+
+Black (88 columns, double quotes), Ruff, `mypy --strict`. Type hints with
+`typing.List/Dict/Optional/Union`, `os.path` instead of `pathlib`, Google-style
+docstrings with typed `Args:`, `Returns:`, `Raises:`. Comments only for a
+non-obvious *why*. Docstrings describe behaviour for users, not development
+rules.
+
+## Do not modify without explicit instruction
+
+- `_internal/hashing.py` and `study_identity` (study ids and digests depend on
+  the exact bytes hashed).
+- The wire models in `_internal/schemas.py` (versioned change, bump
+  `API_VERSION`).
+
+## Commands
+
+```bash
+pip install -e ".[dev]"
+pytest tests/unit -q
+pytest tests/integration -q     # needs the quantum extra
+ruff check src/ tests/
+black --check src/ tests/
+mypy src/intelloptim/
+nox                             # the same checks, across Python versions
+```
+
+## Development notes
+
+The maintainer keeps additional design notes in `.claude/notes/`. They are not
+part of the repository; ask for them when working in these areas:
+
+- samplers and benchmarking (statelessness rules, sampler choice, honest
+  benchmarking)
+- quantum samplers (design, cohort/snapshot mechanics, hardware guards, limits)
+- sampler plugins (entry-point contract, adding a built-in sampler kind)
+- documentation conventions (docstring style, checklist after public-surface
+  changes)