core-labs/core
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
core/docs/specs/foundational-families/quantity-entity-binding.md

7.6 KiB
Raw Permalink Blame History

Foundational Family Specification: Quantity-Entity Binding

Status: Proposed (gating specification) Related ADRs: ADR-0223, ADR-0224 Domains: Arithmetic/Quantitative, Physical Science, Charts/Tables/Data, Social Studies Summary: This family defines the structural binding of a quantified scalar value to the semantic entity, object, or category it measures. Quantity-entity binding is the foundational prerequisite for all relational reasoning: before a rate, partition, comparison, or state change can be computed, the quantities themselves must be unambiguously anchored to their semantic referents.

Surface / chunk patterns:

  • <number> <noun> (e.g., "5 apples", "12 grams")
  • <number> of the <noun> (e.g., "three of the boxes")
  • <noun>: <number> (e.g., "Population: 50,000", "Red group: 12")
  • <number> <unit> of <material> (e.g., "5 kg of iron")

Semantic neighborhood:

  • quantified_group
  • measured_property
  • category_cardinality
  • resource_population

Construction signatures:

Signature: quantity_entity_binding
Future adapter: quantity_entity_adapter
Relation Type: quantity_entity

Required roles:

  • quantity: The GroundedMention pointing to a ScalarCandidate representing the numerical value (including fractions, percents, or integers).
  • entity: The GroundedMention pointing to the noun, noun phrase, or category that the quantity measures.

Optional roles:

  • unit: The GroundedMention pointing to the measurement unit (e.g., "meters", "dollars"), if the quantity is dimensional.

Hazards / confusers:

  • PF-EN-002 quantity_entity_unbound: A quantity appears adjacent to another quantity modifier rather than a noun (e.g., "3 more").
  • PF-LX-004 span_collision: Numeric homophones or compound words leading to overlapping/competing scalar candidate spans (e.g., "one half-hour" -> "one", "one half", "half-hour").
  • PF-EN-005 role_alias_collision: Same surface denotes different subgroups or objects (e.g., "5 red apples and 3 green ones" where "ones" is an alias for "apples").
  • PF-HZ-005 conflict_auto_resolved: Confused reference mapping when multiple entities of the same category are mentioned in close proximity.

ProblemFrame / domain-frame representation:

# Typed bindings and relations representing quantity-entity alignment
from dataclasses import dataclass

@dataclass(frozen=True)
class GroundedMention:
    mention_id: str
    surface: str
    start: int
    end: int
    fact_id: str | None = None  # Links to GroundedScalar, GroundedUnit, etc.

@dataclass(frozen=True)
class MentionBinding:
    binding_id: str
    binding_type: str  # "quantity_entity" | "quantity_unit"
    source_mention_id: str  # GroundedMention.mention_id of quantity
    target_mention_id: str  # GroundedMention.mention_id of entity/unit

ContractAssessment readiness criteria: A candidate quantity-entity binding reaches RUNNABLE status if and only if:

  1. The quantity mention is successfully grounded to a parsed GroundedScalar with exact numeric fraction values (PF-LX-001 resolved).
  2. The entity mention is successfully resolved to a valid noun phrase or category within the sentence span (PF-EN-001 resolved).
  3. No active overlap or span collisions exist (PF-LX-004 resolved).
  4. No unresolved hazard category is active (e.g., quantity_entity_unbound checks pass).

Verification style:

  • Invariance under lexical substitution (e.g., substituting "apples" with "oranges" must result in identical binding topology, modulo spans).
  • Confuser rejection (e.g., "3 more than 5" must bind "5" to its entity and flag "3" as comparative, refusing generic binding for "3").

Refusal conditions:

  • Presence of unresolved ambiguous referents (e.g., "them" or "ones" in "there are 5 apples and 3 of them" when multiple candidate entities are active and ungrounded).
  • Multi-scalar overlap collisions that cannot be deterministically ordered.

Cross-domain evidence:

  1. Physical Science (Measurement):
    • Example: "A block of iron has a mass of 12 grams."
    • Bindings: 
      GroundedMention(mention_id="m-qty", surface="12", start=34, end=36, fact_id="scalar-0001")
GroundedMention(mention_id="m-unit", surface="grams", start=37, end=42, fact_id="unit-0001")
GroundedMention(mention_id="m-entity", surface="iron", start=10, end=14, fact_id="entity-0001")

MentionBinding(binding_id="b-qty-ent", binding_type="quantity_entity", source_mention_id="m-qty", target_mention_id="m-entity")
MentionBinding(binding_id="b-qty-unit", binding_type="quantity_unit", source_mention_id="m-qty", target_mention_id="m-unit")
  2. Charts/Tables (Category Counts):
    • Example: "The bar graph shows: Apples: 15, Bananas: 8."
    • Bindings: 
      GroundedMention(mention_id="m-qty-1", surface="15", start=32, end=34, fact_id="scalar-0001")
GroundedMention(mention_id="m-ent-1", surface="Apples", start=24, end=30, fact_id="entity-0001")
GroundedMention(mention_id="m-qty-2", surface="8", start=46, end=47, fact_id="scalar-0002")
GroundedMention(mention_id="m-ent-2", surface="Bananas", start=36, end=43, fact_id="entity-0002")

MentionBinding(binding_id="b-qty-ent-1", binding_type="quantity_entity", source_mention_id="m-qty-1", target_mention_id="m-ent-1")
MentionBinding(binding_id="b-qty-ent-2", binding_type="quantity_entity", source_mention_id="m-qty-2", target_mention_id="m-ent-2")
  3. Social Studies (Demographics):
    • Example: "The town of Shelbyville has a population of 50,000 residents."
    • Bindings: 
      GroundedMention(mention_id="m-qty", surface="50,000", start=47, end=53, fact_id="scalar-0001")
GroundedMention(mention_id="m-ent-town", surface="Shelbyville", start=12, end=23, fact_id="entity-0001")
GroundedMention(mention_id="m-ent-pop", surface="residents", start=54, end=63, fact_id="entity-0002")

MentionBinding(binding_id="b-qty-ent", binding_type="quantity_entity", source_mention_id="m-qty", target_mention_id="m-ent-pop")
  4. Arithmetic / GSM-style Pressure Lane:
    • Example: "Joan has 5 marbles. She gives 3 marbles to Todd."
    • Bindings: 
      GroundedMention(mention_id="m-qty-1", surface="5", start=9, end=10, fact_id="scalar-0001")
GroundedMention(mention_id="m-ent-1", surface="marbles", start=11, end=18, fact_id="entity-0001")
GroundedMention(mention_id="m-qty-2", surface="3", start=31, end=32, fact_id="scalar-0002")
GroundedMention(mention_id="m-ent-2", surface="marbles", start=33, end=40, fact_id="entity-0001")

MentionBinding(binding_id="b-qty-ent-1", binding_type="quantity_entity", source_mention_id="m-qty-1", target_mention_id="m-ent-1")
MentionBinding(binding_id="b-qty-ent-2", binding_type="quantity_entity", source_mention_id="m-qty-2", target_mention_id="m-ent-2")

Serving status: Not implemented / not serving. Current state relies on ad-hoc regex heuristic extraction within local parsers. Assessment-backed proposal traces for selected math constructions exist in diagnostics, but general CGA/substrate retrieval does not yet support this family.

Implementation authorization: AUTHORIZED ONLY AS A BOUNDED FUTURE DIAGNOSTIC SLICE. The controlling authorization is docs/sessions/quantity-entity-foundational-slice-authorization-2026-06-20.md. It becomes effective only after that authorization PR merges. It permits the proposal-first binding.quantity_entity slice described there and nothing broader: no serving, state-change semantics, general entity extraction, broad parsing, or answer production.