Development setup

Requirements

Python 3.12 or newer
Git
uv
Optional network access and official DICOM artifacts for integration tests

Create the environment

git clone https://github.com/beatrice-b-m/dicom-standard-kb.git
cd dicom-standard-kb
uv sync --all-extras --dev

Equivalent Make target:

make install

The full environment includes:

runtime parser and CLI dependencies;
optional MCP support;
Ruff;
mypy;
pytest;
snapshot and property-based testing dependencies.

Run a first diagnostic

uv run dicom-kb doctor
uv run dicom-kb --help

Build the synthetic database

uv run dicom-kb build-fixture \
  --edition 2026b \
  --db /tmp/dicom-kb-dev.sqlite \
  --force

Run a representative query:

uv run dicom-kb lookup tag Modality \
  --edition 2026b \
  --db /tmp/dicom-kb-dev.sqlite

This gives a fast local feedback loop without official downloads.

Run the offline quality gates

make lint
make typecheck
make test

Or invoke the underlying tools directly:

uv run --dev ruff check .
uv run --dev mypy
uv run --dev pytest

The mypy configuration is strict. Fix typing at the boundary rather than silencing it broadly.

Repository areas

src/dicom_kb/
  cli/        command adapter
  db/         models, migrations, importers, repositories
  docbook/    generic document parsing
  eval/       agent cases, runners, scoring, reports
  ir/         canonical records and validation
  mcp/        stdio server, tool schemas, dispatch
  parsers/    part-specific semantic parsing
  query/      public resolvers, graph logic, citations, contracts
  sources/    acquisition, edition resolution, manifests, verification

Top-level build.py orchestrates parsing and SQLite import. config.py validates profiles and resolves precedence.

Generated data

Keep source artifacts and generated databases outside the repository. The default cache is ignored and lives under:

~/.cache/dicom-standard-kb

Use /tmp or another explicit test directory for disposable development builds.

Before editing

Read:

the source repository AGENTS.md;
the relevant existing tests;
the implemented source, not only SYSTEM_SPECS.md;
the legal and distribution policy for fixture or output changes.

SYSTEM_SPECS.md records design intent and older planned scope. Current code, tests, and user-facing contracts determine implemented behavior where they differ.