Build an official-edition knowledge base

Build a real knowledge base by acquiring official DICOM artifacts into your local cache and parsing their DocBook XML into SQLite.

1. Fetch the current official release

uv run dicom-kb fetch --edition current

The command discovers the concrete edition from official current-release metadata, downloads the baseline DocBook XML parts, and writes an immutable source manifest.

Record the concrete edition in the JSON output. The manifest also records that it was resolved_from current.

The default structured-build part set is:

PS3.3
PS3.4
PS3.5
PS3.6
PS3.7
PS3.8
PS3.10
PS3.16
PS3.18

2. Build SQLite

Set EDITION to the value returned by fetch. The assignment below uses a concrete historical example:

EDITION=2025e  # Replace with your concrete edition.
uv run dicom-kb build --edition "$EDITION"

The default database path is:

~/.cache/dicom-standard-kb/db/<concrete-edition>.sqlite

The build refuses to overwrite an existing database unless --force is explicit.

3. Verify the build

EDITION=2025e  # Replace with your concrete edition.
uv run dicom-kb verify --edition "$EDITION"

Verification checks:

the source manifest’s own digest;
the existence and SHA-256 digest of each cached artifact;
the database build-metadata record, when the database exists;
matching concrete edition and source-manifest digest.

A missing database is reported as a warning after artifact verification. Other manifest, checksum, or metadata mismatches fail verification.

4. Run a first official lookup

EDITION=2025e  # Replace with your concrete edition.
uv run dicom-kb lookup tag Modality \
  --edition "$EDITION"

Confirm that the response edition matches the build and inspect its refs, classification, parse_confidence, and trace.

Fetch a historical edition

Concrete editions are discovered in the official archive before download:

uv run dicom-kb fetch --edition 2025e
uv run dicom-kb build --edition 2025e
uv run dicom-kb verify --edition 2025e

An edition label must match the concrete 20YYx form and exist in the official archive listing.

Fetch selected parts

Repeat --part to restrict acquisition:

uv run dicom-kb fetch \
  --edition current \
  --part PS3.5 \
  --part PS3.6

A partial cache can support the corresponding parser and text surfaces, but queries that depend on missing parts may return not_found, candidates, or incomplete graph context. Use the full baseline part set for release verification.

Cache additional official formats

SQLite builds read docbook_xml. Other formats can be cached for local inspection or citation verification:

uv run dicom-kb fetch \
  --edition current \
  --part PS3.6 \
  --format docbook_xml \
  --format pdf

Supported formats are:

docbook_xml
pdf
html
chtml
targetdb

By default, chtml fetches the part entry page. Mirror its full part directory only when needed:

uv run dicom-kb fetch \
  --edition current \
  --part PS3.6 \
  --format chtml \
  --mirror-chtml-tree

Register local DocBook XML

Use existing local source files instead of downloading:

uv run dicom-kb fetch \
  --edition 2025e \
  --docbook-xml PS3.6=/path/to/part06.xml

Repeat --docbook-xml PART=PATH for additional parts. The command copies each file into the cache, computes its digest, and writes the same manifest model used by official downloads.

Use an explicit cache or database path

EDITION=2025e  # Replace with your concrete edition.
uv run dicom-kb fetch \
  --edition current \
  --cache-dir /data/dicom-standard-kb

uv run dicom-kb build \
  --edition "$EDITION" \
  --cache-dir /data/dicom-standard-kb \
  --db /data/dicom-standard-kb/custom.sqlite

uv run dicom-kb verify \
  --edition "$EDITION" \
  --cache-dir /data/dicom-standard-kb \
  --db /data/dicom-standard-kb/custom.sqlite

Keep the cache, database, and edition aligned. The database records the source manifest digest used to create it.

Enforce ingestion thresholds

Add quality gates when you have established acceptable values for an edition:

EDITION=2025e  # Replace with your concrete edition.
uv run dicom-kb build \
  --edition "$EDITION" \
  --max-unresolved-xref-rate 0.05 \
  --max-unresolved-include-rate 0.0 \
  --max-parse-warnings 0

A gate failure prints the completed build summary and exits nonzero. Use --allow-gate-failures only while establishing a baseline; the failures remain visible in gate_failures and warnings.

See Verify a build and enforce quality gates for a review workflow and Build metrics and quality gates for exact fields.