src.dackar.knowledge_graph.temporal_relations

Allen’s interval-algebra classification for the temporal-relation schema.

Dependency-free helper (standard library only) so it can be unit-tested without pandas or a Neo4j driver. It computes the qualitative temporal relation between two events for the temporally_related.allen_relation property defined in schemas/temporalRelationSchema.toml.

Both time-instant events (t_end omitted / None -> treated as a zero-length interval at t_start) and time-interval events are supported. When an instant coincides with an interval endpoint, the point is treated as part of the interval (starts / finishes) rather than as merely touching it (meets / met_by).

The returned string is always one of ALLEN_RELATIONS, matching the enum values in the schema exactly.

Attributes

ALLEN_RELATIONS

Functions

_coerce(value)	Coerce value to a comparable scalar.
_check_timezone_policy(values)	Enforce a uniform timezone policy across the datetime endpoints.
allen_relation(a_start, a_end, b_start, b_end)	Return the Allen relation of interval/instant A to B for edge (A)->(B).

Module Contents

src.dackar.knowledge_graph.temporal_relations.ALLEN_RELATIONS = ('before', 'after', 'meets', 'met_by', 'overlaps', 'overlapped_by', 'starts', 'started_by',...

src.dackar.knowledge_graph.temporal_relations._coerce(value)

Coerce value to a comparable scalar.

ISO-8601 strings are parsed to datetime; datetime/date and numeric values are returned unchanged. A string that is not valid ISO-8601 is rejected with ValueError rather than returned for lexicographic comparison, which would silently produce false temporal relations (e.g. "9" > "10" as strings).

src.dackar.knowledge_graph.temporal_relations._check_timezone_policy(values)

Enforce a uniform timezone policy across the datetime endpoints.

Timezone-aware and naive datetime values cannot be compared in Python (it raises TypeError), and silently assuming a timezone would invent data. The explicit policy is therefore: every datetime endpoint in a single call must be uniformly timezone-aware or uniformly naive.

src.dackar.knowledge_graph.temporal_relations.allen_relation(a_start, a_end, b_start, b_end)

Return the Allen relation of interval/instant A to B for edge (A)->(B).

Parameters:

• a_start – Start of A (t_start). Required.

• a_end – End of A (t_end); None for a time-instant event.

• b_start – Start of B (t_start). Required.

• b_end – End of B (t_end); None for a time-instant event.

Returns:

One of ALLEN_RELATIONS describing how A relates to B.

Raises:

ValueError – if a timestamp string is not valid ISO-8601, if timezone- aware and naive datetimes are mixed, if the endpoints are not mutually comparable, or if either event’s end precedes its start.