Plugin Development

Plugin Development

DQ QuestionBank Core exposes four extension protocols.

Built-in adapters

• QuestionImporter: JSON, Markdown, LaTeX, DOCX
• QuestionExporter: JSON, Markdown, LaTeX, DOCX

Extension points (no built-in implementation)

StorageAdapter

class StorageAdapter(Protocol):
    def save(self, question_set: QuestionSet) -> None: ...
    def load(self, question_set_id: str) -> QuestionSet: ...

Use for PostgreSQL, SQLite, S3, or any backend. The open-source core never calls this protocol. Private projects import, implement, and wire it.

AIProvider

class AIProvider(Protocol):
    def enrich(self, question_set: QuestionSet, **options: Any) -> QuestionSet: ...

Intended for private AI enrichment: tag suggestions, difficulty estimation, answer generation. Credentials must live in environment variables or a private config file, never in question metadata.

Registering custom adapters

from dq_questionbank import FormatRegistry

registry = FormatRegistry()
registry.register_importer(MyCustomImporter())
registry.register_exporter(MyCustomExporter())

question_set = registry.importer("my-format").load(source_path)
registry.exporter("json").dump(question_set, output_path)

Since v0.2.0, register_importer and register_exporter enforce the protocol with isinstance checks.

Exception handling

All library exceptions inherit from QuestionBankError:

from dq_questionbank import (
    QuestionBankError,
    FormatDetectionError,
    FormatLoadError,
    FormatWriteError,
    SchemaNotFoundError,
    SchemaValidationError,
    SchemaVersionError,
)

See also: plugin-development.md