Skip to content

AnnotationModel

dorsal.common.model.AnnotationModel 

AnnotationModel(file_path)

The abstract base class for all Annotation Models in the pipeline.

An Annotation Model is processes a file and returns a structured dictionary of metadata (an Annotation).

See: AnnotationModel docs

1. The Input Contract (Attributes)

When the ModelRunner instantiates your model, it automatically populates instance attributes before calling main().

Attributes:

Name Type Description
file_path str

The absolute path to the file on disk.
media_type str | None

The IANA Media Type (e.g., 'application/pdf') identified by the Base model.
extension str | None

The file extension (lowercase, e.g., '.docx').
size int | None

The file size in bytes.
hash str | None

The SHA-256 hash of the file.
name str | None

The filename (e.g., 'report.pdf').
follow_symlinks bool

Defaults to True. - True (Target Mode): This model analyzes the file content. If path is a symlink, the link is resolved to its target. - False (Link Mode): Trust the path provided, even if it is a symlink. Useful if you want to analyse symbolic links.
2. The Output Contract (Return Values)

Your subclass must implement the main() method, which must return:

  • dict: A dictionary containing the extracted metadata. Validates against the schema ID configured for this model in the pipeline.
  • None: To indicate that the model ran successfully but found no relevant data, or encountered a handled error.
3. Identity (Class Attributes)

To ensure annotations are traceable and unique, your subclass must define:

  • id (str): A global identifier (e.g., "github:dorsalhub/pdf-model").
  • version (str): Semantic version of the model logic (e.g., "1.0.0").
  • variant (str, optional): Specific engine or config used (e.g., "v2-large").
4. Error Handling

Do not raise exceptions for expected failures. Call self.set_error("Reason") and return None.

Initializes the model, setting the file_path.

Source code in venv/lib/python3.12/site-packages/dorsal/common/model.py 
114
115
116
117
118
119
120
121
122
123
124
def __init__(self, file_path: str):
    """Initializes the model, setting the file_path."""
    self.file_path = file_path
    self.error: str | None = None
    self.name: str | None = None
    self.extension: str | None = None
    self.size: int | None = None
    self.media_type: str | None = None
    self.hash: str | None = None
    self.similarity_hash: str | None = None
    self.quick_hash: str | None = None

__init_subclass__ 

__init_subclass__(**kwargs)

Sets 'id' and 'version' if they are not provided.

Source code in venv/lib/python3.12/site-packages/dorsal/common/model.py 
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
def __init_subclass__(cls, **kwargs):
    """Sets 'id' and 'version' if they are not provided."""
    super().__init_subclass__(**kwargs)

    if not hasattr(cls, "id") or cls.id is None:
        safe_name = cls.__name__[:256] or "unnamed-model"
        logger.warning(
            f"'{cls.__name__}' does not define an 'id'. "
            f"Defaulting to '{safe_name}'.\n"
            f"For setting model `id` for discoverability see: {DOCS_URL}/reference/annotation-model"
        )
        cls.id = safe_name

    else:
        try:
            cls.id = apply_pydantic_validator(value=cls.id, validator=String256)
        except PydanticValidationError as err:
            safe_name = cls.__name__[:256] or "unnamed-model"
            cls.id = safe_name
            logger.debug(err)
            logger.warning(
                f"`{cls.__name__}.id` (`{cls.id}`) is not a valid Model ID. "
                f"Defaulting to '{safe_name}'.\n"
                f"For setting model `id` for discoverability see: {DOCS_URL}/reference/annotation-model"
            )

log_debug 

log_debug(message)

Logs a debug message with standardized model context.

Source code in venv/lib/python3.12/site-packages/dorsal/common/model.py 
143
144
145
146
147
148
149
150
151
def log_debug(self, message: str):
    """Logs a debug message with standardized model context."""
    logger.debug(
        "Model '%s' (v%s) for file '%s': %s",
        self.id,
        self.version,
        self.file_path,
        message,
    )

main 

main(*args, **kwargs)

The main entrypoint for the annotation model. This method must be implemented by the subclass.

  • On success: return a dictionary of the annotation data.
  • On graceful failure: call self._set_error("reason") and return None.
  • On critical failure: raise an Exception (e.g., a missing dependency).
Source code in venv/lib/python3.12/site-packages/dorsal/common/model.py 
153
154
155
156
157
158
159
160
161
162
def main(self, *args, **kwargs) -> dict | None:
    """
    The main entrypoint for the annotation model.
    This method must be implemented by the subclass.

    - On success: return a dictionary of the annotation data.
    - On graceful failure: call self._set_error("reason") and return None.
    - On critical failure: raise an Exception (e.g., a missing dependency).
    """
    raise NotImplementedError("The `main` method must be implemented by the subclass.")

set_error 

set_error(message, level=logging.DEBUG)

Sets a graceful error message for the model and logs it.

Call this and return None from main() for non-critical, expected failures (e.g., file is not the right type).

Source code in venv/lib/python3.12/site-packages/dorsal/common/model.py 
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
def set_error(self, message: str, level: int = logging.DEBUG):
    """
    Sets a graceful error message for the model and logs it.

    Call this and return None from `main()` for non-critical,
    expected failures (e.g., file is not the right type).
    """
    logger.log(
        level,
        "Model '%s' (v%s) failed for file '%s': %s",
        self.id,
        self.version,
        self.file_path,
        message,
    )
    self.error = message