Architecture for contributors

The implementation is a Python core with thin CLI and MCP adapters around one SQLite-backed resolver layer.

Component flow

sources
  -> docbook
    -> parsers
      -> ir
        -> db importers and migrations
          -> query repositories and resolvers
            -> CLI / Python / MCP

The evaluation package exercises tool routing across the public resolver surface.

Source acquisition

dicom_kb.sources owns:

• official current and archive URL discovery;
• concrete-edition validation;
• local artifact registration;
• cache destinations;
• SHA-256 calculation;
• source-manifest persistence;
• cache and database verification.

Do not add a download path that stores a mutable current label as the edition.

Generic DocBook parsing

dicom_kb.docbook preserves reusable structural information before semantic interpretation.

A part-specific parser should consume this representation rather than reimplement XML traversal independently when the generic structure is sufficient.

Preserve:

• stable anchors;
• row ordering;
• cross-references;
• source locations;
• warning information;
• bounded text content.

Part-specific parsers

dicom_kb.parsers converts relevant structures into canonical semantic records.

A parser should:

• recognize narrowly defined structures;
• normalize identifiers deterministically;
• retain raw or explanatory text needed for review;
• emit warnings for unsupported variants;
• avoid guessing a link from weak name similarity;
• attach a source reference to every normative record.

Intermediate representation

dicom_kb.ir decouples parsing from persistence. Models should be typed, edition aware through import context, and explicit about optional or unresolved fields.

Identifier validation belongs close to shared IR/query boundaries so CLI, Python, and MCP receive consistent behavior.

Database layer

dicom_kb.db owns:

• schema migrations;
• transactional imports;
• build metadata;
• repository queries;
• relationship records.

Add a migration rather than mutating an old schema in place. Keep edition and source-reference keys on semantic tables.

The reviewed source uses SQLite only. Do not introduce PostgreSQL behavior into documentation or public APIs until implemented and tested.

Resolver layer

dicom_kb.query.resolver is the public behavioral core. Resolvers should:

1. validate and normalize inputs;
2. query repositories;
3. traverse graph relationships deterministically;
4. preserve candidates or ambiguity;
5. construct official references;
6. assign the shared response classification and confidence;
7. return a ToolResponse for normal outcomes.

Do not place independent business logic in CLI or MCP adapters.

Public adapters

CLI

Typer commands resolve configuration and paths, open SQLite read-only, call one resolver, and serialize JSON.

Python

Callers import resolver functions directly and manage the connection.

MCP

The adapter registers typed functions, maps MCP arguments to one resolver call, and serializes the same public response. Keep the edition and database fixed at server startup.

Adding a new structured query

A typical sequence is:

1. identify the official DocBook structure and source-reference strategy;
2. add or extend canonical IR models;
3. add a schema migration and repository record;
4. implement transactional import;
5. add synthetic parser fixtures;
6. add parser and importer tests;
7. add the resolver and result contract;
8. define evidence classification and confidence behavior;
9. add CLI exposure;
10. add MCP metadata, registration, and dispatch if agent-facing;
11. add Python, CLI, MCP, and JSON-schema tests;
12. add agent-regression cases when routing changes;
13. update coverage, reference, legal, and release documentation;
14. run offline and applicable official-edition gates.

Invariants to protect

• no official bulk content enters the package or repository;
• every normative fact can identify its official source;
• query connections are read-only;
• build and import paths remain deterministic;
• warnings remain observable;
• public adapters remain behaviorally aligned;
• text retrieval remains bounded;
• a new tool cannot silently downgrade ambiguity into a guessed answer.