picsure 2.0.0__tar.gz

picsure-2.0.0/.devcontainer/devcontainer.json

@@ -0,0 +1,25 @@
+{
+  "name": "picsure-dev",
+  "dockerComposeFile": ["../docker-compose.yml"],
+  "service": "dev",
+  "workspaceFolder": "/workspace",
+  "remoteUser": "dev",
+  "overrideCommand": true,
+  "customizations": {
+    "vscode": {
+      "settings": {
+        "python.defaultInterpreterPath": "/opt/venv/bin/python",
+        "python.terminal.activateEnvironment": false,
+        "python.testing.pytestEnabled": true,
+        "python.testing.pytestArgs": ["tests"],
+        "ruff.path": ["/opt/venv/bin/ruff"],
+        "mypy-type-checker.path": ["/opt/venv/bin/mypy"]
+      },
+      "extensions": [
+        "ms-python.python",
+        "ms-python.mypy-type-checker",
+        "charliermarsh.ruff"
+      ]
+    }
+  }
+}

picsure-2.0.0/.dockerignore

@@ -0,0 +1,33 @@
+# The repo is bind-mounted at runtime, so the build context only needs
+# what the Dockerfile actually COPYs (docker/entrypoint.sh). Keep this
+# tight to make `docker compose build` fast.
+
+# Build/cache artifacts
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.eggs/
+*.egg
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+site/
+
+# Editor / IDE
+.idea/
+.vscode/
+*.iml
+
+# Local state
+.worktrees/
+.env
+.git/
+.github/
+
+# Docs that aren't needed during build
+docs/superpowers/

picsure-2.0.0/.env.example

@@ -0,0 +1,16 @@
+# Copy to `.env` and fill in values to run integration tests without
+# exporting env vars on every shell. Shell-exported vars override these.
+
+PICSURE_INTEGRATION=1
+PICSURE_TEST_PLATFORM=BDC_PREDEV_AUTHORIZED
+PICSURE_TEST_TOKEN=
+
+# Concept path used by query and export live tests. Must exist on the
+# target deployment — this one works on BDC_DEV_OPEN / BDC_PREDEV_*.
+# For a different platform, pick a path returned by a dictionary search
+# (e.g. via `session.search("age")`).
+PICSURE_TEST_CONCEPT_PATH=\open_access-1000Genomes\SIMULATED AGE\
+
+# Search term used by search live tests. "age" works on most PIC-SURE
+# deployments. Override if your target dataset uses different terms.
+PICSURE_TEST_SEARCH_TERM=age

picsure-2.0.0/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # hatch-vcs reads git history/tags for the version
+      - uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+      - run: uv sync --frozen
+      - run: uv run ruff check src/ tests/
+      - run: uv run ruff format --check src/ tests/
+      - run: uv run mypy src/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # hatch-vcs reads git history/tags for the version
+      - uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+      - run: uv python install ${{ matrix.python-version }}
+      - run: uv sync --frozen --python ${{ matrix.python-version }}
+      - run: uv run pytest tests/unit/ -v --cov=picsure --cov-fail-under=80

picsure-2.0.0/.github/workflows/docs.yml

@@ -0,0 +1,31 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # hatch-vcs reads git history/tags for the version
+
+      - uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - run: uv sync --frozen --group docs
+
+      - name: Build docs (strict mode catches broken references)
+        run: uv run mkdocs build --strict
+
+      - name: Deploy to GitHub Pages
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: site

picsure-2.0.0/.github/workflows/release.yml

@@ -0,0 +1,111 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+# Least privilege by default; jobs opt into what they need.
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # hatch-vcs reads git history/tags for the version
+      - uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+      - run: uv sync --frozen
+      - run: uv run ruff check src/ tests/
+      - run: uv run ruff format --check src/ tests/
+      - run: uv run mypy src/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+      - run: uv python install ${{ matrix.python-version }}
+      - run: uv sync --frozen --python ${{ matrix.python-version }}
+      - run: uv run pytest tests/unit/ -v --cov=picsure --cov-fail-under=80
+
+  build:
+    needs: [lint, test]
+    runs-on: ubuntu-latest
+    outputs:
+      prerelease: ${{ steps.classify.outputs.prerelease }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # required: full history + tags so hatch-vcs derives the tagged version
+
+      - name: Classify tag (final vs pre-release)
+        id: classify
+        run: |
+          tag="${GITHUB_REF_NAME}"
+          if [[ "$tag" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "prerelease=false" >> "$GITHUB_OUTPUT"
+            echo "Final release: $tag -> PyPI"
+          elif [[ "$tag" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(a|b|rc)[0-9]*$ ]]; then
+            echo "prerelease=true" >> "$GITHUB_OUTPUT"
+            echo "Pre-release: $tag -> TestPyPI"
+          else
+            echo "::error::Tag '$tag' is not vMAJOR.MINOR.PATCH or a PEP 440 pre-release (e.g. v2.0.0, v2.0.0rc1, v2.0.0rc)"
+            exit 1
+          fi
+
+      - uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: Check distribution metadata
+        run: uvx twine check dist/*
+
+      - uses: actions/upload-artifact@v4
+        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: TestPyPi
+    permissions:
+      id-token: write # OIDC token for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    needs: build
+    if: needs.build.outputs.prerelease == 'false'
+    runs-on: ubuntu-latest
+    environment: PyPi
+    permissions:
+      id-token: write # OIDC token for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

picsure-2.0.0/.gitignore

@@ -0,0 +1,50 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+.env
+.venv/
+venv/
+*.iml
+.idea/
+.vscode/
+site/
+.worktrees/
+docs/superpowers
+docs/superpowers/
+
+# JupyterLab artifacts written into the source tree from the dev container
+.ipynb_checkpoints/
+
+# Only commit notebooks that live under notebooks/. Anything elsewhere
+# (Untitled.ipynb in the repo root, scratch experiments inside src/,
+# accidental notebooks from container sessions) stays out of git.
+*.ipynb
+!notebooks/**/*.ipynb
+
+# Generated PFB / Avro export artifacts from the export notebooks (nb 7)
+*.avro
+
+# XDG trash directory created when a container process "deletes" a file
+.Trash-*/
+
+# Credentials sometimes pasted into the workspace
+token.txt
+token*.txt
+*.token
+
+# local scratch (HAR captures, ad-hoc temp files); never commit
+docs/tmp/
+*.har
+
+# collect_env_metrics.py output (per-env latency baselines); never commit
+metrics-results/

picsure-2.0.0/.python-version

@@ -0,0 +1 @@
+3.10

picsure-2.0.0/CHANGELOG.md

@@ -0,0 +1,117 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/).
+
+## [Unreleased]
+
+## [2.0.0] - 2026-06-15
+
+### Changed
+- **BREAKING:** The query builders are renamed to a `build*` triplet whose names match their return types: `createSubQuery` → `buildClause` (returns `Clause`), the clause-combining `buildQuery` → `buildClauseGroup` (returns `ClauseGroup`). The name `buildQuery` is now the query *assembler* `buildQuery(phenotypicFilter=None, includeConcepts=())` and returns a `Query`.
+- **BREAKING:** `Query` is now a dataclass (`phenotypicFilter`, `includeConcepts`) rather than a `Clause | ClauseGroup` type alias. `runQuery`/`exportAsPFB`/`saveQueryByName` accept a `Query` or a bare `Clause`/`ClauseGroup`. A saved query that selects output concepts now loads as a `Query` (previously a `ClauseGroup` of `SELECT` clauses).
+
+### Removed
+- **BREAKING:** `PhenotypicFilterType.SELECT` is removed. To include concept paths in the output without filtering, pass them to `buildQuery(includeConcepts=...)` instead of building a `SELECT` clause.
+
+### Added
+- `picsure.buildGenomicFilter(key, *, values)` builds a single categorical genomic filter. `values` is required (string or list of strings); `VariantFrequency` members are accepted and coerced. Variant-spec and SNP keys are rejected with an actionable error.
+- `picsure.genomicConsequences()` returns an offline DataFrame of all variant consequences with a `severity` and `consequence` column. Available on any platform; no network call.
+- `picsure.buildQuery(genomicFilters=None)` - `buildQuery` now accepts an optional `genomicFilters` list. Genomic filters are AND-combined with the phenotypic filter; a genomic-only query (no `phenotypicFilter`) is valid.
+- `picsure.connect(supports_genomic=None)` - `connect` accepts an optional `supports_genomic` flag for platforms that do not auto-detect genomic capability. Genomic operations are available on BDC_AUTHORIZED, BDC_DEV_AUTHORIZED, BDC_PREDEV_AUTHORIZED, and NHANES_AUTHORIZED; all `*_OPEN` platforms are not genomic-capable.
+- `Session.searchGenomicValues(genomicConceptPath, *, query="", page=1, size=50)` performs a paginated server lookup of valid values for any genomic key (genes, consequences). Returns a pandas DataFrame; pagination metadata is on `df.attrs`. Available on authorized platforms only.
+- `GenomicFilter` dataclass representing a single categorical genomic filter (`key`, `values`).
+- `VariantFrequency` enum with members `RARE`, `COMMON`, and `NOVEL` for use with the `Variant_frequency_as_text` genomic key.
+- Variant result types for `runQuery`: `variant_count` (returns `CountResult`), `variant_list` (returns `list[str]`), `vcf_excerpt` (returns DataFrame), and `aggregate_vcf_excerpt` (returns DataFrame). These types are not served by BDC primary environments yet; the adapter raises `PicSureQueryError` with a clear message on an empty or 5xx response.
+- `picsure.buildQuery(phenotypicFilter=None, includeConcepts=())` assembles a `Query` from a filter tree plus the concept paths to return as output columns. `includeConcepts` preserves order and de-duplicates.
+- `picsure.removeSubQuery(query, target)` returns a copy of `query` with every structurally-equal occurrence of `target` removed, recursively through nested groups. Emptied `ClauseGroup`s are dropped. Raises `PicSureValidationError` if the whole tree would be removed.
+- `picsure.replaceClause(query, target, replacement)` returns a copy of `query` with every structurally-equal occurrence of `target` swapped for `replacement`.
+- `Session.saveQueryByName(query, name, *, overwrite=False)` submits the query via `POST /picsure/v3/query` and associates `name` with it via `POST /dataset/named/`. With `overwrite=True`, an existing record with the same name is `PUT`-updated to point at the freshly-submitted query. The backend's `NamedDataset` constraints (`name` max 255 chars, allowed: letters, digits, spaces, ``- _ \ / ? + = [ ] . ( ) : " '``) are validated client-side. Refused on open-access deployments. Returns the new query ID — pass it to `loadQueryByID` / `runQueryByID` later.
+- `PicSureClient.put_json()` on the transport client (used by the `saveQueryByName` overwrite path).
+- `picsure.PicSureAuthError`, `picsure.PicSureConnectionError`, `picsure.PicSureQueryError`, and `picsure.PicSureValidationError` are now re-exported from the top-level package, so `from picsure import PicSureQueryError` works (previously required `from picsure.errors import ...`).
+- `Session.facets(term="", *, facets=None)` and `Session.showAllFacets(term="", *, facets=None)` now accept optional search term and facet selections. Counts returned are contextual to the provided search when term/facets are supplied; passing no arguments preserves the previous "global counts" behaviour.
+- `DictionaryEntry` exposes `min`, `max`, `allow_filtering`, `meta`, and `study_acronym` fields. The corresponding columns (`min`, `max`, `allowFiltering`, `meta`, `studyAcronym`) are added to the `Session.searchDictionary` DataFrame result.
+- `picsure.connect()` to authenticate and connect to a PIC-SURE instance.
+- `Session.getResourceID()` to list available resources as a DataFrame.
+- Platform name resolution for BDC Authorized, BDC Open, and Demo.
+- Actionable error messages via `PicSureError`.
+- Unit test suite with mocked HTTP via respx.
+- Integration test scaffold gated by `PICSURE_INTEGRATION` env var.
+- GitHub Actions CI with Python 3.10/3.11/3.12 matrix.
+- `Session.searchDictionary()` to search the data dictionary with optional facet filtering.
+- `Session.facets()` to retrieve available facet categories as a `FacetSet`.
+- `Session.showAllFacets()` to display all facet categories and values as a DataFrame.
+- `FacetSet` for building facet selections with validation.
+- Search result deduplication by concept path.
+- Zero-result searches return empty DataFrames with a stderr note.
+- `picsure.createSubQuery()` to build individual filter clauses (FILTER, ANYRECORD, SELECT, REQUIRE).
+- `picsure.buildQuery()` to combine clauses with AND/OR logic, supporting arbitrary nesting.
+- `PhenotypicFilterType` and `GroupOperator` enums for type-safe clause and group construction.
+- `Clause`, `ClauseGroup`, and `Query` types with `to_query_json()` serialization.
+- `CountResult` dataclass exposing `value`, `margin`, `cap`, `raw`, and an `obfuscated` property for count query responses.
+- Input validation with actionable error messages for invalid clause configurations.
+- `Session.runQuery()` to execute queries and return a `CountResult`, a `dict[str, CountResult]` (cross-count), or a `DataFrame` (participant / timestamp).
+- `Session.runQueryByID(query_id, type="count")` to load a saved query by ID and execute it in one call, returning the same result types as `runQuery`.
+- `Session.exportAsPFB()` to export query results as PFB files.
+- `Session.exportCSV()` and `Session.exportTSV()` to save DataFrames to disk.
+- `PicSureClient.post_raw()` for non-JSON response handling.
+- Query type validation with actionable error messages ("count", "participant", "timestamp").
+- Documentation site with MkDocs + Material theme.
+- Auto-generated API reference from docstrings via mkdocstrings.
+- User guides: search, facets, query building, running, and exporting.
+- Migration guide from PicSureHpdsLib with side-by-side examples.
+- Docs CI workflow: build on PR, deploy to GitHub Pages on push to main.
+
+### Changed
+- `Session.runQuery` docstring now documents that ``participant`` / ``timestamp``
+  DataFrame cells may contain tab-joined multi-values; callers should use
+  ``df[col].str.split("\t")`` when they need individual observations.
+- Query endpoint changed from `/picsure/query/sync` to `/picsure/v3/query/sync`.
+- `Clause.to_query_json()` / `ClauseGroup.to_query_json()` now emit the v3 `PhenotypicClause` / `PhenotypicSubquery` schema (`operator` / `phenotypicClauses` / `not` for groups; `phenotypicFilterType` / `conceptPath` / `values` / `min` / `max` / `not` for leaves). The previous wire format is no longer produced.
+- `Clause.to_query_json()` now raises `PicSureValidationError` for `SELECT` clauses. Use `Clause.select_paths()` / `ClauseGroup.select_paths()` to retrieve output paths instead.
+- `Session.runQuery(..., type="count")` now returns a `CountResult` dataclass instead of a plain `int`. Access the integer count via `result.value`; check `result.cap` for suppressed small-count responses (`result.value` is `None` in that case) and `result.margin` for noisy responses.
+- `Session.runQuery(..., type="cross_count")` now returns a `dict[str, CountResult]` keyed by concept path instead of a DataFrame.
+- `PicSureClient` now strips leading/trailing whitespace from the bearer token; a whitespace-only token is treated as anonymous (no `Authorization` header, `request-source: Open`).
+- `Session.exportAsPFB()` / `picsure._services.export.export_pfb` now use the async flow (`POST /picsure/v3/query` → poll `/query/{id}/status` → `POST /query/{id}/result`) rather than `/query/sync`. Response bytes are streamed directly to disk. Polling uses exponential backoff (1s, 2s, 4s, … capped at 60s per poll) and fails with `PicSureConnectionError` after 10 minutes of cumulative waiting. The output file is written atomically (`.part` staging file + rename on success).
+- `createSubQuery` now raises `PicSureValidationError` for additional invalid combinations:
+  FILTER clauses with both `categories` and `min`/`max`; REQUIRE or SELECT clauses
+  with any of `categories`/`min`/`max`; empty keys lists. These were previously
+  silently accepted and the extra arguments discarded (or rejected downstream by
+  the server with a less actionable error).
+- `ClauseGroup.to_query_json()` now raises `PicSureValidationError` if any nested
+  child is a SELECT clause (previously it silently stripped them). This is
+  symmetric with `Clause.to_query_json()`, which has always raised on SELECT.
+  `ClauseGroup.select_paths()` and `build_query_body()` continue to handle SELECT
+  extraction at the top level; inline SELECTs inside a group are the error case.
+- `createSubQuery` now defensively copies list arguments (`keys`, `categories`), so
+  mutating the caller's lists after construction does not affect the resulting
+  `Clause`.
+- Dependency ranges tightened to upper-bounded majors (`httpx>=0.27,<1`, `pandas>=2,<3`) to avoid silent breakage on major releases.
+- `CONTRIBUTING.md` lint instructions now cover both `src/` and `tests/`, matching the CI gate.
+
+### Removed
+- Wire-format docstrings on `Clause` and `ClauseGroup` no longer advertise the
+  `not` / negation field. The adapter still emits `"not": False` on the wire, but
+  negation is not supported by the public API; support will return in a later
+  release.
+
+### Fixed
+- `Session.runQuery(..., type="participant")` and `type="timestamp"` now surface
+  malformed-CSV responses as `PicSureQueryError` with a body preview (previously
+  leaked raw pandas `ParserError` / `EmptyDataError` / `UnicodeDecodeError`).
+- `Session.runQuery(..., type="cross_count")` explicitly handles the direct-HPDS
+  response shape (`{concept_path: integer}`), not only the aggregate-obfuscation
+  response shape (`{concept_path: count_string}`).
+- `Session.runQuery` now validates the query argument at body construction so
+  that passing a plain `dict` raises `PicSureValidationError` ("Query must be a
+  Clause or ClauseGroup") rather than a confusing `AttributeError` from an
+  internal accessor.
+- `Session.searchDictionary` now raises `PicSureQueryError` when the server's paginated response indicates the result set was truncated (`last != True` or `content` length doesn't match `totalElements`). Previously the adapter silently returned the partial page.
+- PFB export against v3 PIC-SURE was silently broken: the previous implementation posted `DATAFRAME_PFB` to `/query/sync`, which v3 HPDS has no handler for. Unit tests passed only because `respx` served a canned 200 body at the wrong URL.
+- 4xx responses during PFB submission / status / result are now surfaced as `PicSureValidationError` / `PicSureQueryError` (previously the 4xx body bytes would be written to disk as if they were PFB).
+- `OSError` / `PermissionError` during disk writes in `export_pfb` are now wrapped in `PicSureConnectionError` with the target path in the message (previously leaked raw).
+- Getting-started and search-and-facets guide examples used ``"study_ids"`` as the facet category; the server returns ``"dataset_id"``. Guides updated to match. Users copy-pasting the earlier examples would have seen ``PicSureValidationError``.
+- ``showAllFacets`` DataFrame column list in the user guide was outdated. Now correctly documents the six columns (``category``, ``Category Display``, ``display``, ``description``, ``value``, ``count``).
+- Raw-string code snippets ending in a backslash (e.g. ``r"\phs1\sex\"``) were unterminated string literals and would ``SyntaxError`` on copy-paste. Replaced with doubled-backslash non-raw strings across ``README.md`` and the guides.
+- API reference now documents `Platform`, `CountResult`, the `PicSureError` subclasses, and `Session.consents` / `Session.total_concepts` properties, which were exported but missing from the reference.

picsure-2.0.0/CONTRIBUTING.md

@@ -0,0 +1,85 @@
+# Contributing
+
+Welcome. This document is the entry point for working on `picsure`
+itself — both new contributors getting set up and maintainers handling
+day-to-day reviews, tests, and releases. User-facing usage docs live
+under [`docs/`](docs/) and on the published site; this file and the
+[`docs/development/`](docs/development/) folder are for people
+**changing the library**.
+
+## Where to find things
+
+| Topic                                  | Where                                                  |
+|----------------------------------------|--------------------------------------------------------|
+| Containerized dev environment + IDEs   | [docs/development/docker.md](docs/development/docker.md) |
+| Package layout and internals           | [docs/development/architecture.md](docs/development/architecture.md) |
+| Test layout, running, debugging CI     | [docs/development/testing.md](docs/development/testing.md) |
+| Versioning, tagging, publishing        | [docs/development/releasing.md](docs/development/releasing.md) |
+
+## Local development setup
+
+Prefer a container? See
+[docs/development/docker.md](docs/development/docker.md) for a
+pre-configured Docker dev environment (no local `uv` or Python
+required, JupyterLab included). That guide also covers
+[IDE setup for VS Code and PyCharm](docs/development/docker.md#ide-setup--using-the-containers-python-from-your-editor).
+
+For a host-native setup:
+
+1. Install [uv](https://docs.astral.sh/uv/getting-started/installation/).
+
+2. Clone the repo and install dependencies:
+
+   ```bash
+   git clone https://github.com/hms-dbmi/pic-sure-python-adapter-hpds.git
+   cd pic-sure-python-adapter-hpds
+   uv sync
+   ```
+
+3. Run the checks:
+
+   ```bash
+   uv run ruff check src/ tests/            # lint
+   uv run ruff format --check src/ tests/   # format check (both src and tests)
+   uv run mypy src/                         # type check
+   uv run pytest tests/unit/ -v             # unit tests
+   ```
+
+These four commands mirror the CI lint gate, which runs `ruff check`
+and `ruff format --check` over **both** `src/` and `tests/`. Skipping
+`tests/` locally will let contributor-written test files pass the
+local check but fail CI.
+
+## Branching and pull requests
+
+- Branch from `main`. Use short, descriptive branch names.
+- Write descriptive commit messages. The existing history follows a
+  loose conventional-commits style (`feat(query):`, `fix(client):`,
+  `chore(deps):`, `refactor(session):`, `docs(...)`). Match it when
+  it's natural; don't fight the linter if it isn't.
+- Open the PR against `main`. CI must pass before merge:
+  - **Lint job** — `ruff check src/ tests/`, `ruff format --check
+    src/ tests/`, `mypy src/`.
+  - **Test matrix** — `pytest tests/unit/` on Python 3.10, 3.11, 3.12
+    with `--cov-fail-under=80`.
+  - **Docs** — `mkdocs build --strict` (broken cross-references fail
+    the build).
+- If you touched the public API surface (anything re-exported from
+  `picsure/__init__.py`), update `CHANGELOG.md` under `[Unreleased]`.
+
+## Code style
+
+- `ruff` handles linting and formatting. Config lives in
+  `pyproject.toml` under `[tool.ruff]`.
+- `mypy --strict` enforces type annotations on all code in `src/`.
+- Google-style docstrings on all public functions.
+- camelCase for public API method names (matches the product spec);
+  snake_case for everything internal.
+
+## Where to file issues
+
+GitHub Issues on the repo:
+<https://github.com/hms-dbmi/pic-sure-python-adapter-hpds/issues>.
+
+For security-sensitive reports, please coordinate with the
+maintainers privately before opening a public issue.