Struct Signal 

pub struct Signal<L = Location> {
    pub id: SignalId,
    pub location: L,
    pub surface: String,
    pub label: TypeLabel,
    pub confidence: f32,
    pub hierarchical: Option<HierarchicalConfidence>,
    pub provenance: Option<Provenance>,
    pub modality: Modality,
    pub normalized: Option<String>,
    pub negated: bool,
    pub quantifier: Option<Quantifier>,
}

A raw detection signal: the atomic unit of entity extraction.

The Detection Equation

Every signal is the product of two factors:

Signal = Localization × Classification
       = "where is it?" × "what is it?"

This is true whether detecting faces in images, named entities in text, or objects in LiDAR point clouds.

Design Philosophy

Signals are intentionally minimal. They capture:

1. Where: Location in the source medium
2. What: Classification label + confidence
3. Provenance: How it was detected

What they explicitly do NOT capture:

• Coreference relationships (→ Track)
• Knowledge base links (→ Identity)
• Semantic embeddings (computed lazily if needed)

This separation enables efficient streaming pipelines where signals are produced incrementally and consumed by downstream track/identity formation without blocking.

Fields

id: SignalId

Unique identifier within the document

location: L

Location in the source medium

surface: String

Surface form (the actual text or image patch)

label: TypeLabel

Classification label (e.g., “Person”, “Organization”, “PER”).

Stored as a TypeLabel to support both core taxonomy types and domain-specific labels.

confidence: f32

Detection confidence in [0, 1]

hierarchical: Option<HierarchicalConfidence>

Hierarchical confidence if available (linkage/type/boundary)

provenance: Option<Provenance>

Provenance: which detector produced this signal

modality: Modality

Semiotic modality (derived from location, but can be overridden)

normalized: Option<String>

Normalized form (e.g., “Jan 15” → “2024-01-15”)

negated: bool

Whether this signal is negated (e.g., “not a doctor”)

quantifier: Option<Quantifier>

Quantification if applicable (e.g., “every employee”)

Implementations

impl<L> Signal<L>

pub fn new( id: impl Into<SignalId>, location: L, surface: impl Into<String>, label: impl Into<TypeLabel>, confidence: f32, ) -> Self

Create a new signal.

Arguments

• id - Unique identifier (will be overwritten when added to a document)
• location - Where this signal was detected
• surface - The actual text/content of the detection
• label - Classification label (e.g., “Person”, “Organization”)
• confidence - Detection confidence in [0, 1]

pub fn label(&self) -> &str

Get the classification label as a string.

pub fn type_label(&self) -> TypeLabel

Get the classification label as a type-safe TypeLabel.

pub fn surface(&self) -> &str

Get the surface form.

pub fn is_confident(&self, threshold: f32) -> bool

Check if this signal is above a confidence threshold.

pub fn with_modality(self, modality: Modality) -> Self

Set the modality.

pub fn negated(self) -> Self

Mark as negated.

pub fn with_quantifier(self, q: Quantifier) -> Self

Set quantifier.

pub fn with_provenance(self, p: Provenance) -> Self

Set provenance.

impl Signal<Location>

pub fn text_offsets(&self) -> Option<(usize, usize)>

Get text offsets if this is a text signal.

pub fn validate_against( &self, source_text: &str, ) -> Option<SignalValidationError>

Validate that this signal’s location matches its surface text.

Returns None if valid, or a description of the mismatch.

Example

use anno_core::grounded::{Signal, Location};

let text = "Lynn Conway worked at IBM.";
let good = Signal::new(0, Location::text(0, 11), "Lynn Conway", "PER", 0.9);
assert!(good.validate_against(text).is_none());

let bad = Signal::new(0, Location::text(0, 5), "Lynn Conway", "PER", 0.9);
assert!(bad.validate_against(text).is_some());

pub fn is_valid(&self, source_text: &str) -> bool

Check if this signal is valid against the given source text.

pub fn from_text( source: &str, surface: &str, label: impl Into<TypeLabel>, confidence: f32, ) -> Option<Self>

Create a signal by finding text in source (safe construction).

Returns None if the surface text is not found in source.

Example

use anno_core::grounded::{Signal, Location};

let text = "Lynn Conway worked at IBM.";
let signal = Signal::<Location>::from_text(text, "Lynn Conway", "PER", 0.95);
assert!(signal.is_some());
assert_eq!(signal.expect("signal should exist").text_offsets(), Some((0, 11)));

pub fn from_text_nth( source: &str, surface: &str, label: impl Into<TypeLabel>, confidence: f32, occurrence: usize, ) -> Option<Self>

Create a signal by finding the nth occurrence of text in source.

Trait Implementations

impl<L: Clone> Clone for Signal<L>

fn clone(&self) -> Signal<L>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<L: Debug> Debug for Signal<L>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de, L> Deserialize<'de> for Signal<L>

where L: Deserialize<'de>,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<L: PartialEq> PartialEq for Signal<L>

fn eq(&self, other: &Signal<L>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<L> Serialize for Signal<L>

where L: Serialize,

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<L> StructuralPartialEq for Signal<L>