dimsechord 0.3.0__tar.gz

dimsechord-0.3.0/.claude/hooks/block-branch-switch.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+# PreToolUse hook for Bash: blocks branch switching in the root project directory.
+# Use EnterWorktree to work on a different branch.
+
+INPUT=$(cat)
+if command -v jq >/dev/null 2>&1; then
+  COMMAND=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty')
+else
+  COMMAND=$(printf '%s' "$INPUT" | grep -oP '"command"\s*:\s*"\K[^"]*' || true)
+fi
+[ -z "$COMMAND" ] && exit 0
+
+# Check for git checkout/switch (not file-restore variant)
+if ! echo "$COMMAND" | grep -qP 'git\s+(checkout|switch)\b'; then
+  exit 0
+fi
+
+# Allow file restore: `git checkout [<rev>] -- <path>` / `git switch ... -- <path>`.
+# The `--` (and any preceding revision) must belong to this checkout/switch, not a
+# later chained command, so the match cannot cross a ;, & or | separator.
+if echo "$COMMAND" | grep -qP 'git\s+(checkout|switch)\b[^;&|]*\s--(\s|$)'; then
+  exit 0
+fi
+
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0
+
+# Check that we're in the root directory (not a worktree)
+GIT_DIR=$(git rev-parse --git-dir 2>/dev/null)
+COMMON_DIR=$(git rev-parse --git-common-dir 2>/dev/null)
+
+if [ "$(realpath "$GIT_DIR")" = "$(realpath "$COMMON_DIR")" ]; then
+  cat >&2 <<'EOF'
+BLOCKED: Branch switching in the root project directory is not allowed.
+Use EnterWorktree to work on a different branch.
+`git checkout -- <file>` for restoring files is still available.
+EOF
+  exit 2
+fi
+
+exit 0

dimsechord-0.3.0/.claude/hooks/pr-monitor.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# PostToolUse hook: detect `gh pr create`, start background monitoring.
+
+INPUT=$(cat)
+
+echo "$INPUT" | grep -q "gh pr create" || exit 0
+echo "$INPUT" | grep -qE "(--help|--dry-run)" && exit 0
+
+PR_URL=$(echo "$INPUT" | grep -oP 'https://github\.com/[^"]+/pull/\d+' | head -1)
+[ -z "$PR_URL" ] && exit 0
+
+PR_NUM=$(echo "$PR_URL" | grep -oP '\d+$')
+REPORT="/tmp/pr-${PR_NUM}-report.md"
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Fully detach the watcher into its own session so it survives the hook's
+# process-group teardown (nohup alone only ignores SIGHUP, not SIGTERM/SIGKILL).
+if command -v setsid >/dev/null 2>&1; then
+  setsid "$HOOK_DIR/pr-watch.sh" "$PR_NUM" 12 300 </dev/null >/dev/null 2>&1 &
+else
+  nohup "$HOOK_DIR/pr-watch.sh" "$PR_NUM" 12 300 </dev/null >/dev/null 2>&1 &
+  disown
+fi
+
+cat >&2 <<EOF
+PR_CREATED: PR #${PR_NUM} (${PR_URL}).
+Background CI monitor started (PID $!, polling every 5 min, max 1 hour).
+Report: ${REPORT}
+When the user asks about PR status, read ${REPORT}.
+EOF
+
+exit 2

dimsechord-0.3.0/.claude/hooks/pr-watch.sh

@@ -0,0 +1,58 @@
+#!/bin/bash
+# Background PR monitor — polls GitHub CI checks and writes report.
+# Usage: pr-watch.sh <PR_NUMBER> [max_iterations] [interval_seconds]
+
+set -euo pipefail
+
+PR_NUM="${1:?Usage: pr-watch.sh <PR_NUMBER>}"
+MAX_ITER="${2:-12}"
+INTERVAL="${3:-300}"
+REPORT="/tmp/pr-${PR_NUM}-report.md"
+
+echo "# PR #${PR_NUM} — Monitoring started $(date -Iseconds)" > "$REPORT"
+echo "Checking every ${INTERVAL}s, max ${MAX_ITER} iterations." >> "$REPORT"
+
+for ((i=1; i<=MAX_ITER; i++)); do
+    # Poll before sleeping so an already-finished CI is reported immediately.
+    # gh pr checks exit codes: 0=all pass, 1=some failed, 8=pending, other=error.
+    if CHECKS=$(gh pr checks "$PR_NUM" 2>&1); then RC=0; else RC=$?; fi
+    STATUS_JSON=$(gh pr view "$PR_NUM" --json statusCheckRollup,comments,reviews,state 2>&1) || true
+
+    # Only treat an authoritative pass(0)/fail(1) as terminal; pending(8) and any
+    # gh error keep us waiting instead of writing a false "complete" report.
+    if [ "$RC" -eq 0 ] || [ "$RC" -eq 1 ]; then
+        cat > "$REPORT" <<REPORT_EOF
+# PR #${PR_NUM} — CI Complete ($(date -Iseconds))
+
+## Check Results
+\`\`\`
+${CHECKS}
+\`\`\`
+
+## Reviews & Comments
+\`\`\`json
+${STATUS_JSON}
+\`\`\`
+REPORT_EOF
+        exit 0
+    fi
+
+    echo "Iteration ${i}/${MAX_ITER}: checks not final (gh rc=${RC}, $(date -Iseconds))" >> "$REPORT"
+    sleep "$INTERVAL"
+done
+
+cat > "$REPORT" <<REPORT_EOF
+# PR #${PR_NUM} — Monitoring Timeout ($(date -Iseconds))
+
+Gave up after ${MAX_ITER} iterations ($(( MAX_ITER * INTERVAL / 60 )) minutes).
+
+## Last Check Results
+\`\`\`
+${CHECKS:-no data}
+\`\`\`
+
+## Reviews & Comments
+\`\`\`json
+${STATUS_JSON:-no data}
+\`\`\`
+REPORT_EOF

dimsechord-0.3.0/.claude/hooks/require-worktree-agent.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+# PreToolUse hook for Agent: only read-only agents may run on the main branch.
+# Any agent that can mutate files must run inside a worktree, so analysis and
+# edits happen in the same context.
+
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0
+
+BRANCH=$(git branch --show-current 2>/dev/null)
+[ "$BRANCH" != "main" ] && [ "$BRANCH" != "master" ] && exit 0
+
+INPUT=$(cat)
+if command -v jq >/dev/null 2>&1; then
+  SUBAGENT=$(printf '%s' "$INPUT" | jq -r '.tool_input.subagent_type // empty')
+else
+  SUBAGENT=$(printf '%s' "$INPUT" | grep -oP '"subagent_type"\s*:\s*"\K[^"]*' || true)
+fi
+
+# Allowlist: read-only agents (no Edit/Write/NotebookEdit) may run on main.
+# Everything else — including write-capable general-purpose agents — is blocked,
+# so a write-capable agent can never run on main by default (fail-closed).
+case "$SUBAGENT" in
+  Explore|Plan|feature-dev:code-explorer|feature-dev:code-reviewer|claude-code-guide)
+    exit 0
+    ;;
+esac
+
+cat >&2 <<'EOF'
+BLOCKED: This agent can modify files and may not run on the main branch.
+Use EnterWorktree before launching development or architecture agents.
+This ensures analysis and subsequent changes happen in the same worktree.
+(Read-only agents such as Explore/Plan/code-explorer/code-reviewer are allowed.)
+EOF
+exit 2

dimsechord-0.3.0/.claude/hooks/require-worktree.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+# PreToolUse hook: blocks Edit/Write on the main branch.
+# All changes require a worktree or feature branch.
+
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0
+
+# Skip files outside the repository (plan files, global .claude/, etc.)
+INPUT=$(cat)
+if command -v jq >/dev/null 2>&1; then
+  FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty')
+else
+  FILE_PATH=$(printf '%s' "$INPUT" | grep -oP '"file_path"\s*:\s*"\K[^"]*' || true)
+fi
+if [ -n "$FILE_PATH" ]; then
+  REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+  case "$FILE_PATH" in
+    "$REPO_ROOT"/.claude/*) exit 0 ;; # infrastructure files — always allow
+    "$REPO_ROOT"/*) ;;                # file in repo — check further
+    *) exit 0 ;;                      # file outside repo — skip
+  esac
+fi
+
+BRANCH=$(git branch --show-current 2>/dev/null)
+
+if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
+  cat >&2 <<'EOF'
+BLOCKED: Editing files on the main branch is not allowed.
+Use EnterWorktree before making changes.
+EOF
+  exit 2
+fi
+
+exit 0

dimsechord-0.3.0/.claude/hooks/worktree-stop.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+# Stop hook: blocks session end in a worktree,
+# so Claude asks the user what to do with changes.
+
+INPUT=$(cat)
+
+# Prevent infinite loop — skip on retry
+if echo "$INPUT" | grep -qE '"stop_hook_active"\s*:\s*true'; then
+  exit 0
+fi
+
+# Debounce per session: don't block again within 120 seconds.
+# Key on the session id (stable, collision-free) rather than a reusable PPID.
+if command -v jq >/dev/null 2>&1; then
+  SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // empty')
+fi
+[ -z "${SESSION_ID:-}" ] && SESSION_ID="$PPID"
+DEBOUNCE_FILE="/tmp/claude-worktree-stop-${SESSION_ID}"
+if [ -f "$DEBOUNCE_FILE" ]; then
+  LAST=$(cat "$DEBOUNCE_FILE" 2>/dev/null || echo 0)
+  NOW=$(date +%s)
+  if [ $((NOW - LAST)) -lt 120 ]; then
+    exit 0
+  fi
+fi
+
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0
+
+# Check that this is a worktree (not the main repo)
+GIT_DIR=$(git rev-parse --git-dir 2>/dev/null)
+GIT_COMMON_DIR=$(git rev-parse --git-common-dir 2>/dev/null)
+if [ "$GIT_DIR" = "$GIT_COMMON_DIR" ]; then
+  exit 0
+fi
+
+BRANCH=$(git branch --show-current 2>/dev/null)
+HAS_CHANGES=$(git status --porcelain 2>/dev/null | head -1)
+AHEAD=$(git rev-list main..HEAD --count 2>/dev/null || git rev-list master..HEAD --count 2>/dev/null || echo "0")
+
+date +%s > "$DEBOUNCE_FILE"
+
+cat >&2 <<EOF
+WORKTREE_PENDING: Session is in a worktree, branch '$BRANCH'.
+Commits ahead of main: $AHEAD
+Uncommitted changes: $([ -n "$HAS_CHANGES" ] && echo "yes" || echo "no")
+
+Before ending, ask the user:
+1) Push branch + create PR to main + ExitWorktree(keep)
+2) Keep worktree (to continue later) — ExitWorktree(keep)
+3) Discard changes + remove worktree — ExitWorktree(remove, discard_changes=true)
+EOF
+
+exit 2

dimsechord-0.3.0/.claude/settings.json

@@ -0,0 +1,60 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/require-worktree.sh",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "Agent",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/require-worktree-agent.sh",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/block-branch-switch.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/pr-monitor.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/worktree-stop.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

dimsechord-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,52 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions: {}
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Verify tag matches package version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          pkg="$(grep -m1 '^version = ' pyproject.toml | sed -E 's/version = "(.*)"/\1/')"
+          if [ "$tag" != "$pkg" ]; then
+            echo "::error::Tag v$tag does not match pyproject version $pkg" >&2
+            exit 1
+          fi
+      - name: Build sdist and wheel
+        run: uv build
+      - name: Check metadata
+        run: uvx twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/dimsechord
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish via Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@release/v1

dimsechord-0.3.0/.gitignore

@@ -0,0 +1,15 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+build/
+dist/
+
+# AI planning artifacts (kept locally, not published)
+docs/superpowers/
+
+# Claude Code local settings
+.claude/settings.local.json

dimsechord-0.3.0/CLAUDE.md

@@ -0,0 +1,13 @@
+# dimsechord
+
+## Worktree Workflow
+
+- Feature development: always enter a worktree via `EnterWorktree` before making changes
+- Any file change needs a worktree — the `require-worktree` hook blocks Edit/Write on `main`; only `.claude/` infrastructure files are exempt
+- Worktrees contain only git-tracked files. `hooks/`, `settings.json`, `settings.local.json` live in `$CLAUDE_PROJECT_DIR/.claude/` and are shared
+- `ExitWorktree(remove)` requires `discard_changes=true` if there are commits not in main
+- For PRs in review prefer `ExitWorktree(keep)` until merge
+- The Stop hook blocks session end in a worktree — ask the user to choose:
+  1. **Push + PR**: commit all → `git push -u origin <branch>` → `gh pr create` → `ExitWorktree(keep)`
+  2. **Keep**: `ExitWorktree(keep)` — worktree stays for later
+  3. **Discard**: `ExitWorktree(remove, discard_changes=true)`

dimsechord-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Denis Nesterov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dimsechord-0.3.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: dimsechord
+Version: 0.3.0
+Summary: Pure-Python building blocks for DICOM and DICOMweb services: DIMSE networking, caching, and DICOM↔JSON conversion.
+Project-URL: Homepage, https://github.com/radionest/dimsechord
+Project-URL: Repository, https://github.com/radionest/dimsechord
+Project-URL: Issues, https://github.com/radionest/dimsechord/issues
+Author: Denis Nesterov
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dicom,dicomweb,dimse,medical-imaging,pacs,pydicom,pynetdicom,wado
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Topic :: System :: Networking
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: cachetools>=7.0.0
+Requires-Dist: pydicom>=2.3.1
+Requires-Dist: pynetdicom>=3.0.4
+Description-Content-Type: text/markdown
+
+# dimsechord
+
+Pure-Python toolkit of composable building blocks for DICOM and DICOMweb services.
+
+`dimsechord` wraps [`pydicom`](https://github.com/pydicom/pydicom) and
+[`pynetdicom`](https://github.com/pydicom/pynetdicom) behind a small, stable
+public API. It gives you the networking, caching, and conversion primitives
+needed to build PACS proxies, DICOMweb gateways, and imaging pipelines — and
+nothing else: there is no bundled HTTP framework and no opinionated request
+handlers, so you bring your own web layer.
+
+## Features
+
+- **DIMSE SCU** — C-FIND, C-STORE, C-MOVE and C-GET, exposed through an async
+  `DicomClient`.
+- **C-STORE SCP** — receive incoming instances with `StorageSCP`.
+- **AssociationPool** — manage multiple AE-Title identities with per-AET
+  concurrency limits.
+- **Two-tier cache** — in-memory + disk, backed by a SQLite instance index.
+- **Streaming pull-engine** — move-to-self retrieval streamed instance by
+  instance, with per-UID request coalescing.
+- **DICOMweb conversion** — DICOM ↔ DICOMweb JSON and `multipart/related`
+  frame responses.
+
+Runtime dependencies are just `pydicom`, `pynetdicom`, and `cachetools`.
+
+## Installation
+
+```bash
+pip install dimsechord
+```
+
+Requires Python 3.12+.
+
+## Quickstart
+
+```python
+import asyncio
+
+from dimsechord import (
+    AssociationPool, DicomCache, DicomClient, DicomNode, PullEngine,
+    SeriesQuery, StorageSCP, StudyQuery, convert_datasets_to_dicom_json,
+)
+
+PACS = DicomNode(aet="PACS", host="127.0.0.1", port=11112)
+
+
+async def main() -> None:
+    # 1. Find studies and series (C-FIND, QIDO-style).
+    client = DicomClient(calling_aet="MYSCU")
+    studies = await client.find_studies(StudyQuery(patient_id="12345"), PACS)
+    series = await client.find_series(
+        SeriesQuery(study_instance_uid=studies[0].study_instance_uid), PACS)
+
+    # 2. Pull a series move-to-self and build DICOMweb JSON (WADO-style).
+    pool = AssociationPool(aets=["MYDEST"])
+    scp = StorageSCP()
+    scp.start(aets=pool.aets, port=11113)
+    # Your PACS must route the AET "MYDEST" back to this SCP's host:port.
+    cache = DicomCache(base_dir="./cache", index_path="./cache/index.db")
+    engine = PullEngine(pool=pool, scp=scp, cache=cache, pacs=PACS)
+    try:
+        cached = await engine.ensure_series(
+            studies[0].study_instance_uid, series[0].series_instance_uid)
+        metadata = convert_datasets_to_dicom_json(
+            list(cached.instances.values()), base_url="https://example.org/dicom-web")
+        print(len(metadata), "instances")
+    finally:
+        scp.stop()
+        cache.shutdown()
+
+
+asyncio.run(main())
+```
+
+## Public API
+
+The supported surface is exactly what `dimsechord/__init__.py` exports
+(`from dimsechord import …`); it is frozen by `tests/unit/test_public_api.py`.
+
+Everything else lives in underscore-prefixed modules (`dimsechord._scu`,
+`dimsechord._cache`, …) and is **private** — importing from those modules is
+unsupported and may break without notice. If you need something that is not
+exported, extend the public surface rather than reaching into a private module.
+
+## Documentation
+
+- [Why dimsechord](docs/why.md) — what problems it solves.
+- [Typing](docs/typing.md) — how the typed API works with mypy/pyright.
+- [Cookbook](docs/cookbook.md) — one recipe per feature.
+- [Gateway tutorial](docs/tutorial-gateway.md) — an end-to-end DICOMweb gateway.
+
+## License
+
+MIT — see [LICENSE](https://github.com/radionest/dimsechord/blob/main/LICENSE).

dimsechord-0.3.0/README.md

@@ -0,0 +1,95 @@
+# dimsechord
+
+Pure-Python toolkit of composable building blocks for DICOM and DICOMweb services.
+
+`dimsechord` wraps [`pydicom`](https://github.com/pydicom/pydicom) and
+[`pynetdicom`](https://github.com/pydicom/pynetdicom) behind a small, stable
+public API. It gives you the networking, caching, and conversion primitives
+needed to build PACS proxies, DICOMweb gateways, and imaging pipelines — and
+nothing else: there is no bundled HTTP framework and no opinionated request
+handlers, so you bring your own web layer.
+
+## Features
+
+- **DIMSE SCU** — C-FIND, C-STORE, C-MOVE and C-GET, exposed through an async
+  `DicomClient`.
+- **C-STORE SCP** — receive incoming instances with `StorageSCP`.
+- **AssociationPool** — manage multiple AE-Title identities with per-AET
+  concurrency limits.
+- **Two-tier cache** — in-memory + disk, backed by a SQLite instance index.
+- **Streaming pull-engine** — move-to-self retrieval streamed instance by
+  instance, with per-UID request coalescing.
+- **DICOMweb conversion** — DICOM ↔ DICOMweb JSON and `multipart/related`
+  frame responses.
+
+Runtime dependencies are just `pydicom`, `pynetdicom`, and `cachetools`.
+
+## Installation
+
+```bash
+pip install dimsechord
+```
+
+Requires Python 3.12+.
+
+## Quickstart
+
+```python
+import asyncio
+
+from dimsechord import (
+    AssociationPool, DicomCache, DicomClient, DicomNode, PullEngine,
+    SeriesQuery, StorageSCP, StudyQuery, convert_datasets_to_dicom_json,
+)
+
+PACS = DicomNode(aet="PACS", host="127.0.0.1", port=11112)
+
+
+async def main() -> None:
+    # 1. Find studies and series (C-FIND, QIDO-style).
+    client = DicomClient(calling_aet="MYSCU")
+    studies = await client.find_studies(StudyQuery(patient_id="12345"), PACS)
+    series = await client.find_series(
+        SeriesQuery(study_instance_uid=studies[0].study_instance_uid), PACS)
+
+    # 2. Pull a series move-to-self and build DICOMweb JSON (WADO-style).
+    pool = AssociationPool(aets=["MYDEST"])
+    scp = StorageSCP()
+    scp.start(aets=pool.aets, port=11113)
+    # Your PACS must route the AET "MYDEST" back to this SCP's host:port.
+    cache = DicomCache(base_dir="./cache", index_path="./cache/index.db")
+    engine = PullEngine(pool=pool, scp=scp, cache=cache, pacs=PACS)
+    try:
+        cached = await engine.ensure_series(
+            studies[0].study_instance_uid, series[0].series_instance_uid)
+        metadata = convert_datasets_to_dicom_json(
+            list(cached.instances.values()), base_url="https://example.org/dicom-web")
+        print(len(metadata), "instances")
+    finally:
+        scp.stop()
+        cache.shutdown()
+
+
+asyncio.run(main())
+```
+
+## Public API
+
+The supported surface is exactly what `dimsechord/__init__.py` exports
+(`from dimsechord import …`); it is frozen by `tests/unit/test_public_api.py`.
+
+Everything else lives in underscore-prefixed modules (`dimsechord._scu`,
+`dimsechord._cache`, …) and is **private** — importing from those modules is
+unsupported and may break without notice. If you need something that is not
+exported, extend the public surface rather than reaching into a private module.
+
+## Documentation
+
+- [Why dimsechord](docs/why.md) — what problems it solves.
+- [Typing](docs/typing.md) — how the typed API works with mypy/pyright.
+- [Cookbook](docs/cookbook.md) — one recipe per feature.
+- [Gateway tutorial](docs/tutorial-gateway.md) — an end-to-end DICOMweb gateway.
+
+## License
+
+MIT — see [LICENSE](https://github.com/radionest/dimsechord/blob/main/LICENSE).