Skip to content

Core API

BaseSignal

Bases: ABC

Abstract base class for all content detection signals.

A 'Signal' is a specialized detector that analyzes content of a specific type (text, image, audio) and produces a probabilistic assessment of whether it is AI-generated.

Subclasses must implement
  • name: Unique string identifier.
  • dtype: Input data type supported.
  • run(): The core detection logic.
Source code in veridex/core/signal.py 
 48
 49
 50
 51
 52
 53
 54
 55
 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
 81
 82
 83
 84
 85
 86
 87
 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
113
114
115
116
117
118
119
120
121
122
123
124
class BaseSignal(ABC):
    """
    Abstract base class for all content detection signals.

    A 'Signal' is a specialized detector that analyzes content of a specific type (text, image, audio)
    and produces a probabilistic assessment of whether it is AI-generated.

    Subclasses must implement:
        - `name`: Unique string identifier.
        - `dtype`: Input data type supported.
        - `run()`: The core detection logic.
    """

    @property
    @abstractmethod
    def name(self) -> str:
        """
        Unique identifier for the signal.

        Returns:
            str: A short, snake_case name (e.g., 'zlib_entropy', 'perplexity').
        """
        pass

    @property
    @abstractmethod
    def dtype(self) -> str:
        """
        Data type this signal operates on.

        Returns:
            str: One of 'text', 'image', 'audio', 'video'.
        """
        pass

    @abstractmethod
    def run(self, input_data: Any) -> DetectionResult:
        """
        Execute the detection logic on the provided input.

        Args:
            input_data (Any): The content to analyze. Type should match `self.dtype` expectations:
                - 'text': `str`
                - 'image': `str` (path), `PIL.Image.Image`, or `numpy.ndarray`
                - 'audio': `str` (path) or `numpy.ndarray` (waveform)
                - 'video': `str` (path)

        Returns:
            DetectionResult: The result containing score, confidence, and metadata.
        """
        pass

    def check_dependencies(self) -> None:
        """
        Optional hook to check if required heavy dependencies are installed.

        This is called before expensive operations or at initialization time.

        Raises:
            ImportError: If required extra dependencies (e.g., torch, transformers) are missing.
        """
        pass

    def detect(self, input_data: Any) -> DetectionResult:
        """
        Public alias for `run()`.

        It is recommended to use this method instead of `run()` directly, as it may include
        future pre/post-processing steps.

        Args:
            input_data (Any): The content to analyze.

        Returns:
            DetectionResult: The detection result.
        """
        return self.run(input_data)

name abstractmethod property

Unique identifier for the signal.

Returns:

Name Type Description
str str

A short, snake_case name (e.g., 'zlib_entropy', 'perplexity').

dtype abstractmethod property

Data type this signal operates on.

Returns:

Name Type Description
str str

One of 'text', 'image', 'audio', 'video'.

run(input_data) abstractmethod

Execute the detection logic on the provided input.

Parameters:

Name Type Description Default
input_data Any

The content to analyze. Type should match self.dtype expectations: - 'text': str - 'image': str (path), PIL.Image.Image, or numpy.ndarray - 'audio': str (path) or numpy.ndarray (waveform) - 'video': str (path)

 required

Returns:

Name Type Description
DetectionResult DetectionResult

The result containing score, confidence, and metadata.
Source code in veridex/core/signal.py 
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
@abstractmethod
def run(self, input_data: Any) -> DetectionResult:
    """
    Execute the detection logic on the provided input.

    Args:
        input_data (Any): The content to analyze. Type should match `self.dtype` expectations:
            - 'text': `str`
            - 'image': `str` (path), `PIL.Image.Image`, or `numpy.ndarray`
            - 'audio': `str` (path) or `numpy.ndarray` (waveform)
            - 'video': `str` (path)

    Returns:
        DetectionResult: The result containing score, confidence, and metadata.
    """
    pass

check_dependencies()

Optional hook to check if required heavy dependencies are installed.

This is called before expensive operations or at initialization time.

Raises:

Type Description
ImportError

If required extra dependencies (e.g., torch, transformers) are missing.
Source code in veridex/core/signal.py 
100
101
102
103
104
105
106
107
108
109
def check_dependencies(self) -> None:
    """
    Optional hook to check if required heavy dependencies are installed.

    This is called before expensive operations or at initialization time.

    Raises:
        ImportError: If required extra dependencies (e.g., torch, transformers) are missing.
    """
    pass

detect(input_data)

Public alias for run().

It is recommended to use this method instead of run() directly, as it may include future pre/post-processing steps.

Parameters:

Name Type Description Default
input_data Any

The content to analyze.

 required

Returns:

Name Type Description
DetectionResult DetectionResult

The detection result.
Source code in veridex/core/signal.py 
111
112
113
114
115
116
117
118
119
120
121
122
123
124
def detect(self, input_data: Any) -> DetectionResult:
    """
    Public alias for `run()`.

    It is recommended to use this method instead of `run()` directly, as it may include
    future pre/post-processing steps.

    Args:
        input_data (Any): The content to analyze.

    Returns:
        DetectionResult: The detection result.
    """
    return self.run(input_data)

DetectionResult

Bases: BaseModel

Standardized output model for all detection signals.

This model encapsulates the result of a detection signal, providing a normalized score, a confidence level, and optional metadata or error information.

Attributes:

Name Type Description
score float

Normalized probability score indicating AI-likelihood. Range [0.0, 1.0], where 0.0 is confidently Human and 1.0 is confidently AI.
confidence float

A measure of the reliability of the score estimation. Range [0.0, 1.0], where 1.0 means the signal is fully confident in its assessment.

Confidence interpretation: - 0.0-0.3: Low confidence (heuristics, untrained models, errors) - 0.4-0.6: Moderate confidence (statistical methods, limited data) - 0.7-0.9: High confidence (trained models with good predictions) - 0.9-1.0: Very high confidence (strong model predictions, clear patterns)

For model-based signals, confidence is extracted from model outputs (softmax probabilities, margins, etc.). For heuristic signals, confidence reflects empirical reliability.
metadata Dict[str, Any]

Dictionary containing signal-specific intermediate values, features, or debug information used to derive the score.
error Optional[str]

Error message if the signal failed to execute. If present, score and confidence should be treated as invalid or default.
Example 
result = DetectionResult(
    score=0.95,
    confidence=0.98,
    metadata={"burstiness": 12.5, "perplexity": 5.2}
)
if result.score > 0.5:
    print("Likely AI-generated")
Source code in veridex/core/signal.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
class DetectionResult(BaseModel):
    """
    Standardized output model for all detection signals.

    This model encapsulates the result of a detection signal, providing a normalized score,
    a confidence level, and optional metadata or error information.

    Attributes:
        score (float): Normalized probability score indicating AI-likelihood.
            Range [0.0, 1.0], where 0.0 is confidently Human and 1.0 is confidently AI.
        confidence (float): A measure of the reliability of the score estimation.
            Range [0.0, 1.0], where 1.0 means the signal is fully confident in its assessment.

            Confidence interpretation:
            - 0.0-0.3: Low confidence (heuristics, untrained models, errors)
            - 0.4-0.6: Moderate confidence (statistical methods, limited data)
            - 0.7-0.9: High confidence (trained models with good predictions)
            - 0.9-1.0: Very high confidence (strong model predictions, clear patterns)

            For model-based signals, confidence is extracted from model outputs (softmax probabilities,
            margins, etc.). For heuristic signals, confidence reflects empirical reliability.

        metadata (Dict[str, Any]): Dictionary containing signal-specific intermediate values,
            features, or debug information used to derive the score.
        error (Optional[str]): Error message if the signal failed to execute.
            If present, `score` and `confidence` should be treated as invalid or default.

    Example:
        ```python
        result = DetectionResult(
            score=0.95,
            confidence=0.98,
            metadata={"burstiness": 12.5, "perplexity": 5.2}
        )
        if result.score > 0.5:
            print("Likely AI-generated")
        ```
    """
    score: float = Field(..., ge=0.0, le=1.0, description="Normalized score indicating AI probability. 0=Human, 1=AI.")
    confidence: float = Field(..., ge=0.0, le=1.0, description="Reliability of the score estimation.")
    metadata: Dict[str, Any] = Field(default_factory=dict, description="Additional signal-specific information.")
    error: Optional[str] = Field(None, description="Error message if the signal failed to execute.")