Skip to content

AnnotationModel

dorsal.common.model.AnnotationModel 

AnnotationModel(file_path)

The base class for all Annotation Models.

See: AnnotationModel docs

Subclasses must implement the main method.

Initializes the model, setting the file_path.

Source code in venv/lib/python3.13/site-packages/dorsal/common/model.py 
82
83
84
85
86
87
88
89
90
91
92
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.13/site-packages/dorsal/common/model.py 
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
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.13/site-packages/dorsal/common/model.py 
110
111
112
113
114
115
116
117
118
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.13/site-packages/dorsal/common/model.py 
120
121
122
123
124
125
126
127
128
129
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)

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

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.13/site-packages/dorsal/common/model.py 
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
def set_error(self, message: str):
    """
    Sets a graceful error message for the model and logs it as a warning.

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