Python resolver API

The public resolver module is:

from dicom_kb.query import resolver

or import individual functions from:

from dicom_kb.query.resolver import lookup_data_element

Connection contract

Every resolver accepts a caller-managed sqlite3.Connection as its first argument and a keyword-only concrete edition.

Recommended connection setup:

import sqlite3
from pathlib import Path


def connect_read_only(path: Path) -> sqlite3.Connection:
    connection = sqlite3.connect(f"file:{path}?mode=ro", uri=True)
    connection.row_factory = sqlite3.Row
    return connection

The CLI additionally enables foreign-key enforcement on its read-only connections. Application code can do the same when desired:

connection.execute("PRAGMA foreign_keys = ON")

Registry and identity functions

Function	Query-specific arguments
lookup_data_element	tag_or_keyword: str
lookup_uid	uid_or_keyword: str
lookup_sop_class	uid_or_name_or_keyword: str
lookup_iod	iod_name: str

Attribute value and graph functions

Function	Query-specific arguments
lookup_enumerated_values	attribute: str, `context: str
lookup_defined_terms	attribute: str, `context: str
list_modules_for_iod	iod_name: str
list_attributes_for_module	module_name: str, expand_macros: bool = False
resolve_attribute_context	attribute: str, `iod_name: str

Encoding functions

Function	Query-specific arguments
lookup_vr	vr: str
lookup_transfer_syntax	uid_or_keyword: str
explain_encoding_rule	topic: str

Media and web-service functions

Function	Query-specific arguments
lookup_media_type	media_type_or_context: str
lookup_dicomweb_transaction	name_or_route: str

Content-mapping functions

Function	Query-specific arguments
lookup_sr_template	tid_or_name: str
lookup_context_group	cid_or_name: str
lookup_code_meaning	code_value: str, `scheme: str

Text functions

Function	Query-specific arguments
retrieve_standard_text	part: str, section_or_anchor: str, max_chars: int = 800
search_standard_text	query: str, `part_filter: str

Return type

Every function returns:

dicom_kb.query.answer_contracts.ToolResponse

Important typed fields include:

response.edition
response.tool
response.input
response.status
response.result
response.classification
response.parse_confidence
response.refs
response.warnings
response.notice
response.trace

Serialize through Pydantic:

payload = response.model_dump(mode="json", exclude_none=True)

Example

from pathlib import Path

from dicom_kb.query.resolver import lookup_transfer_syntax

database = Path("/path/to/edition.sqlite")

with connect_read_only(database) as connection:
    response = lookup_transfer_syntax(
        connection,
        uid_or_keyword="ExplicitVRLittleEndian",
        edition="2025e",  # Replace with the database's concrete edition.
    )

if response.status == "ok":
    print(response.result)
else:
    print(response.status, response.result, response.warnings)

Status behavior

Identifier and query problems normally return a typed response:

• malformed tag, UID, or VR input can produce validation_error;
• absent records produce not_found;
• ambiguity can appear as candidates or warnings in an ok result.

Opening a missing database, executing against an incompatible schema, or encountering a lower-level SQLite failure can raise an exception outside the normal answer contract.

Stability boundary

The resolver functions and answer contracts are the public Python surface documented here. Repository classes under db, docbook, ir, parsers, and resolver helper modules are implementation details unless the source project later declares them public.

Prefer resolvers over direct repository or SQL access when building an application-facing answer.