ucwm/specialists/entity.md

Entity Specialist

specialist_id: entity
trigger_gates: has_entity_reference, has_coreference

---

Responsibility

The entity specialist finds named and implied entities, proposes CanonicalObjects for them, resolves aliases, and detects coreference chains. It upgrades proposed objects to active when evidence is sufficient, and emits same_entity or not_same_entity constraints when coreference is resolved.

---

Manifest

declared_facet_kinds:
  - syntactic
  - semantic

declared_constraint_types:
  - same_entity
  - not_same_entity
  - has_role

budget_caps:
  max_objects_proposed:    10
  max_facets_emitted:       8
  max_constraints_emitted: 12
  max_merges:               4
  max_splits:               0

---

Input focus

Given target_refs, the entity specialist inspects:

• Surface text spans that evidence each target object
• Pronouns and alias spans in the same context window
• Prior objects already in WorldState with overlapping spans or labels

---

Output: CanonicalObject proposals

The entity specialist may propose new objects of kind entity. New entity proposals use status: proposed. Proposals are confirmed (active) only if confidence exceeds 0.75.

Required fields on all proposed entities:

• surface_span
• canonical_label
• aliases (may be empty)
• confidence
• source_module: entity

---

Output: SyntacticFacet

For each confirmed entity, emit a SyntacticFacet describing its grammatical role in the input.

SyntacticFacet fields used by entity specialist:
  - grammatical_role: "subject" | "object" | "indirect_object" | "adjunct" | "other"
  - head_token: string

---

Output: Constraints

same_entity

Emit when two object proposals likely refer to the same real-world entity. Common cases:

• Pronoun resolution: she → Alice
• Alias resolution: the company → Acme Corp
• Repeated reference: Alice ... Alice (same span, different positions)

Constraint example:
{
  "constraint_type": "same_entity",
  "argument_refs": ["E1", "E3"],
  "polarity": "positive",
  "strength": "hard",
  "expression": "same_entity(E1, E3)"
}

not_same_entity

Emit when two object proposals are clearly different entities that might otherwise be confused.

Constraint example:
{
  "constraint_type": "not_same_entity",
  "argument_refs": ["E1", "E2"],
  "polarity": "positive",
  "strength": "hard",
  "expression": "not_same_entity(Alice, Bob)"
}

has_role

Emit when an entity is playing a specific functional role in the input context (giver, receiver, buyer, seller, etc.).

Constraint example:
{
  "constraint_type": "has_role",
  "argument_refs": ["E1", "EV_transfer"],
  "polarity": "positive",
  "strength": "soft",
  "expression": "has_role(Alice, giver, EV_transfer)"
}

---

Coreference resolution algorithm (rule-based baseline)

for each pronoun P in input:
  candidates = all active entity objects in WorldState
  rank candidates by:
    1. recency (closest preceding entity)
    2. gender agreement (he/she/they match)
    3. number agreement (they/them = plural)
    4. animacy (personal pronouns prefer animate entities)
  if top candidate confidence > 0.7:
    emit same_entity(pronoun_object, top_candidate)
  else:
    propose new entity with surface_span = P, status = proposed

---

Contract test requirements

• Given Alice gave Bob 2 apples, must emit at least two distinct entity objects (Alice, Bob)
• Must emit not_same_entity(Alice, Bob)
• Given She gave him 2 apples with prior context establishing Alice and Bob, must resolve she → Alice and him → Bob
• Must not emit quantity or temporal constraints
• All emitted objects must have source_module: entity