Struct UncertainReference 

pub struct UncertainReference {
    pub description: String,
    pub candidates: Vec<ReferenceCandidate>,
    pub resolved: bool,
    pub resolved_entity: Option<u64>,
    pub constraints: Vec<ReferenceConstraint>,
    pub discourse_position: Option<usize>,
    pub is_cataphoric: bool,
}

An uncertain reference awaiting resolution.

This is anno’s implementation of epsilon-term semantics for coreference. The reference maintains a distribution over possible antecedents that is refined as more context arrives, allowing deferred commitment.

Lifecycle

1. Create: Initialize with descriptive content (the anaphor)
2. Populate: Add candidate antecedents via add_candidate
3. Refine: Update evidence as context arrives via update_evidence
4. Prune: Remove unlikely candidates via prune or prune_violations
5. Resolve: Force resolution via resolve when needed

Example

use anno::discourse::uncertain_reference::{
    UncertainReference, ReferenceCandidate, ConstraintKind,
};

// Create uncertain reference for "she"
let mut reference = UncertainReference::new("she");

// Add hard constraint: must be feminine
reference.add_constraint(ConstraintKind::Gender, "feminine", true);

// Add candidates
reference.add_candidate(ReferenceCandidate::new(1, "Mary", 0.6));
reference.add_candidate(
    ReferenceCandidate::new(2, "John", 0.4)
        .violates("gender:feminine")
);

// Prune candidates violating hard constraints
reference.prune_violations();
assert_eq!(reference.candidate_count(), 1);

// Resolve
let resolved = reference.resolve().unwrap();
assert_eq!(resolved.entity_id, 1);

Uncertainty Measures

• entropy: Shannon entropy of candidate distribution
• is_ambiguous: Multiple high-probability candidates?
• probabilities: Softmax distribution over candidates

Fields

description: String

Descriptive content — the anaphor text or the “A” in ε_x A[x].

candidates: Vec<ReferenceCandidate>

Candidate referents with weights (in log-odds space).

resolved: bool

Whether resolution has been forced via resolve.

resolved_entity: Option<u64>

The resolved entity ID (set after calling resolve).

constraints: Vec<ReferenceConstraint>

Constraints from the anaphor (gender, number, animacy, etc.). Hard constraints filter candidates; soft constraints rank them.

discourse_position: Option<usize>

Position in discourse (character offset or utterance index).

is_cataphoric: bool

Whether this is cataphoric (forward-referencing). Cataphoric references are resolved when later context provides the antecedent.

Implementations

impl UncertainReference

pub fn new(description: impl Into<String>) -> UncertainReference

Create a new uncertain reference.

pub fn cataphoric(self) -> UncertainReference

Mark as cataphoric (forward-referencing).

pub fn at_position(self, position: usize) -> UncertainReference

Set discourse position.

pub fn add_constraint( &mut self, kind: ConstraintKind, value: impl Into<String>, is_hard: bool, )

Add a constraint.

pub fn add_candidate(&mut self, candidate: ReferenceCandidate)

Add a candidate referent.

pub fn update_evidence(&mut self, entity_id: u64, evidence: f64)

Update evidence for a candidate.

Positive evidence increases weight, negative decreases.

pub fn prune(&mut self, threshold: f64)

Prune candidates below a threshold.

pub fn prune_violations(&mut self)

Prune candidates with hard constraint violations.

pub fn ranked_candidates(&self) -> Vec<&ReferenceCandidate>

Get candidates sorted by weight (highest first).

pub fn best_candidate(&self) -> Option<&ReferenceCandidate>

Get the best candidate (highest weight).

pub fn entropy(&self) -> f64

Compute entropy of the candidate distribution.

Higher entropy = more uncertainty.

pub fn probabilities(&self) -> HashMap<u64, f64>

Convert weights to probabilities (softmax).

pub fn is_ambiguous(&self, threshold: f64) -> bool

Check if resolution is ambiguous (multiple high-probability candidates).

pub fn resolve(&mut self) -> Option<ReferenceCandidate>

Force resolution to the best candidate.

Returns the resolved candidate.

pub fn resolve_to(&mut self, entity_id: u64)

Resolve to a specific entity.

pub fn is_resolved(&self) -> bool

Check if this reference is resolved.

pub fn candidate_count(&self) -> usize

Get the number of candidates.

pub fn is_unresolvable(&self) -> bool

Check if there are no candidates (unresolvable).

Trait Implementations

impl Clone for UncertainReference

fn clone(&self) -> UncertainReference

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for UncertainReference

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

Formats the value using the given formatter.

impl Default for UncertainReference

fn default() -> UncertainReference

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for UncertainReference

fn deserialize<__D>( __deserializer: __D, ) -> Result<UncertainReference, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for UncertainReference

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

where __S: Serializer,

Serialize this value into the given Serde serializer.