graflo.link.statements¶
Which facts hold, given what was stated about them, when, and how.
A statement says that one entity's property has a value, or that it relates
to a target, as one source stated it: affirmed or denied (polarity),
reported as done, intended or uncertain (modality), with the time the
statement says it holds (valid_from / valid_to) and the time it was
said (said_at). A slot is what holds the values: one property, or one
relation from one entity.
:func:resolve turns statements into the facts that hold as_of a time:
- Withdrawals. A denial withdraws the affirmations of the same value said no later than it, or said in the same record or thread when either time is unknown. A denial that cannot be ordered against an affirmation is a conflict.
- Ordering. In a single-valued slot, of two values the one with the later stated time holds; failing stated times on both, the later said time; failing both, the stronger basis (how it was obtained), and the pair is a conflict. A missing time is unknown, never the oldest. Where no value outranks every other, the slot is a conflict and holds nothing.
- Modality. A planned value counts once its whole stated period has
passed by
as_of: the period ends onegranularityunit aftervalid_to, or aftervalid_fromwhen no end is stated (an instant, or no granularity, ends where it starts). Until then, and whenas_ofis not given, it is pending, so a plan is never reported done before it could have happened. A hedged statement never decides a slot; it is pending. - Exclusive slots. A second value is always a conflict; the value with the strongest basis stays current when one has it.
- History. In a stateful slot, each value the current one replaced is kept with its interval, when both are ordered by time.
The result does not depend on the order of the statements. Which slots are
single-valued, exclusive or stateful is read from a schema by
:func:slot_rules. Statements are stored as the provenance aspect's
Assertion vertices (:mod:graflo.link.assertions).
Attributes¶
Granularity = Literal['instant', 'day', 'week', 'month', 'year']
module-attribute
¶
Modality = Literal['actual', 'planned', 'hedged']
module-attribute
¶
Polarity = Literal['stated', 'denied']
module-attribute
¶
SlotId = tuple[str, str]
module-attribute
¶
(vertex_type, slot): which rule applies.
SlotKind = Literal['property', 'relation']
module-attribute
¶
__all__ = ['Basis', 'Conflict', 'Fact', 'Granularity', 'Modality', 'Polarity', 'Resolution', 'SlotKind', 'SlotRule', 'Statement', 'Withdrawal', 'entity_key', 'resolve', 'slot_rules']
module-attribute
¶
Classes¶
Basis
¶
Bases: IntEnum
How a statement was obtained, weakest first; it weighs when time does not decide.
Source code in graflo/link/statements.py
Conflict
¶
Bases: ConfigBaseModel
Values of one slot that nothing orders, or that an exclusive slot refuses.
Source code in graflo/link/statements.py
Fact
¶
Bases: ConfigBaseModel
A value a slot holds, with the statements behind it.
Source code in graflo/link/statements.py
Attributes¶
key
instance-attribute
¶
kind
instance-attribute
¶
modality = 'actual'
class-attribute
instance-attribute
¶
slot
instance-attribute
¶
supports = Field(default_factory=list)
class-attribute
instance-attribute
¶
target_type = None
class-attribute
instance-attribute
¶
valid_from = None
class-attribute
instance-attribute
¶
valid_to = None
class-attribute
instance-attribute
¶
value
instance-attribute
¶
vertex_type
instance-attribute
¶
Resolution
¶
Bases: ConfigBaseModel
What holds as_of, what is pending, what was replaced, withdrawn or disputed.
Source code in graflo/link/statements.py
Attributes¶
conflicts = Field(default_factory=list)
class-attribute
instance-attribute
¶
current = Field(default_factory=list)
class-attribute
instance-attribute
¶
history = Field(default_factory=list)
class-attribute
instance-attribute
¶
pending = Field(default_factory=list)
class-attribute
instance-attribute
¶
withdrawn = Field(default_factory=list)
class-attribute
instance-attribute
¶
SlotRule
¶
Statement
¶
Bases: ConfigBaseModel
One source's statement about one slot.
id left empty is minted from the record, the quote's start, the entity,
the slot and the value, so re-reading the same record gives the same ids.
Source code in graflo/link/statements.py
Attributes¶
basis = Basis.EXTRACTED
class-attribute
instance-attribute
¶
granularity = None
class-attribute
instance-attribute
¶
id = Field(default='', description="Stable id: the stored assertion's key.")
class-attribute
instance-attribute
¶
key = Field(description="The entity's key, as :func:`entity_key` gives it.")
class-attribute
instance-attribute
¶
kind = 'property'
class-attribute
instance-attribute
¶
modality = 'actual'
class-attribute
instance-attribute
¶
polarity = 'stated'
class-attribute
instance-attribute
¶
quote = Field(default=None, description='The words it was read from.')
class-attribute
instance-attribute
¶
record = Field(default=None, description='The record it was read from.')
class-attribute
instance-attribute
¶
said_at = Field(default=None, description="When the source said it: its record's time.")
class-attribute
instance-attribute
¶
slot = Field(description='The property, or the relation, stated.')
class-attribute
instance-attribute
¶
span_end = None
class-attribute
instance-attribute
¶
span_start = None
class-attribute
instance-attribute
¶
target_type = None
class-attribute
instance-attribute
¶
thread = Field(default=None, description='The conversation the record belongs to.')
class-attribute
instance-attribute
¶
valid_from = None
class-attribute
instance-attribute
¶
valid_to = None
class-attribute
instance-attribute
¶
value = Field(description="The property value, or the relation's target key (entity_key).")
class-attribute
instance-attribute
¶
vertex_type
instance-attribute
¶
Withdrawal
¶
Functions:¶
entity_key(doc, fields)
¶
An entity's key as one string: its identity fields, sorted, as JSON.
resolve(statements, rules, *, as_of=None)
¶
The facts that hold as_of, from statements under rules.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
statements
|
Iterable[Statement]
|
Every statement to weigh, in any order. |
required |
rules
|
Mapping[SlotId, SlotRule]
|
Per |
required |
as_of
|
datetime | None
|
The time to resolve at, for planned values. |
None
|
Source code in graflo/link/statements.py
slot_rules(schema)
¶
The single-valued, exclusive and stateful slots schema declares.
A property is single-valued unless it is a LIST that merges by union, and
exclusive when its match declaration says so. A relation is single-valued
with merge: replace and exclusive with exclusive. Either is stateful
when the type's <Type>State carries it. A slot left out is multi-valued.