ClaimFilter

alignment.ClaimFilter(
    timeline_id=None,
    timeline_ids=None,
    id_pattern=None,
    between=None,
    synchronous_only=False,
    nomatch_only=False,
    include_domains=None,
    include_units=None,
)

Reusable filter for querying MatchClaims and related objects.

All fields are optional. When multiple fields are set, they are combined with AND logic: a claim must satisfy every non-None criterion.

The matches_claim() method tests a single MatchClaim against all criteria. The matches_timeline() method tests a single timeline ID (used by MatchGraph node-level filtering).

Examples

Filter for claims involving a specific performer::

f = ClaimFilter(id_pattern=r"^perf:")
filtered = [c for c in claims if f.matches_claim(c)]

Filter for synchronous claims between score and one performer::

f = ClaimFilter(
    between=("score:clt1", "perf:dlt1"),
    synchronous_only=True,
)

Attributes

Name	Type	Description
timeline_id	str | None	Return claims involving this exact timeline ID.
timeline_ids	set[str] | None	Return claims involving any of these timeline IDs.
id_pattern	str | None	Regex pattern matched against timeline IDs via re.search(). Example: r"^perf:" matches all performance timelines.
between	tuple[str, str] | None	Return claims connecting exactly these two timelines (order-independent).
synchronous_only	bool	If True, exclude non-synchronous (NOMATCH) claims.
nomatch_only	bool	If True, return only non-synchronous (NOMATCH) claims.
include_domains	set[Domain] | None	Only include timelines in these domains. Requires a timelines dict for resolution.
include_units	set[TimeUnit] | None	Only include timelines with these units. Requires a timelines dict for resolution.

Methods

Name	Description
domain_unit_timeline_ids	Resolve the domain/unit criteria into the set of ids that pass.
from_kwargs	Create a ClaimFilter from keyword arguments.
matches_claim	Test whether a MatchClaim passes all filter criteria.
matches_timeline	Test whether a single timeline ID passes the filter criteria.

domain_unit_timeline_ids

alignment.ClaimFilter.domain_unit_timeline_ids(timelines)

Resolve the domain/unit criteria into the set of ids that pass.

include_domains / include_units are the only criteria that need per-timeline metadata. Resolving them once into a plain set of timeline ids lets a columnar store — which holds ids but no timeline metadata — apply the same restriction vectorized.

The set carries the same semantics matches_claim applies: a claim passes only when both of its timelines are in it.

Parameters

Name	Type	Description	Default
timelines	dict[str, Timeline] | None	Dict of timeline_id -> Timeline for resolution.	required

Returns

Name	Type	Description
	set[str] | None	None when neither criterion is set (no restriction), else the
	set[str] | None	set of timeline ids satisfying both criteria (empty when
	set[str] | None	timelines is None, mirroring matches_claim).

from_kwargs

alignment.ClaimFilter.from_kwargs(
    timeline_id=None,
    timeline_ids=None,
    id_pattern=None,
    between=None,
    synchronous_only=False,
    nomatch_only=False,
    include_domains=None,
    include_units=None,
)

Create a ClaimFilter from keyword arguments.

Convenience constructor mirroring the canonical filter parameter signature used across the API.

Parameters

Name	Type	Description	Default
timeline_id	str | None	Return claims involving this timeline.	None
timeline_ids	set[str] | None	Return claims involving any of these timelines.	None
id_pattern	str | None	Regex pattern matched against timeline IDs.	None
between	tuple[str, str] | None	Return claims connecting exactly these two timelines.	None
synchronous_only	bool	Exclude non-synchronous claims.	False
nomatch_only	bool	Return only non-synchronous claims.	False
include_domains	set[Domain] | None	Only timelines in these domains.	None
include_units	set[TimeUnit] | None	Only timelines with these units.	None

Returns

Name	Type	Description
	ClaimFilter	A new ClaimFilter.

matches_claim

alignment.ClaimFilter.matches_claim(claim, *, timelines=None)

Test whether a MatchClaim passes all filter criteria.

Parameters

Name	Type	Description	Default
claim	MatchClaim	The MatchClaim to test.	required
timelines	dict[str, Timeline] | None	Dict of timeline_id -> Timeline for resolving domain/unit filters. Required only when include_domains or include_units are set.	None

Returns

Name	Type	Description
	bool	True if the claim passes all filters.

matches_timeline

alignment.ClaimFilter.matches_timeline(timeline_id, *, timelines=None)

Test whether a single timeline ID passes the filter criteria.

Used for node-level filtering in MatchGraph. Only the timeline-ID related filters are applied (timeline_id, timeline_ids, id_pattern, include_domains, include_units). The claim-level filters (synchronous_only, nomatch_only, between) are ignored.

Parameters

Name	Type	Description	Default
timeline_id	str	The timeline ID to test.	required
timelines	dict[str, Timeline] | None	Dict of timeline_id -> Timeline for resolving domain/unit filters.	None

Returns

Name	Type	Description
	bool	True if the timeline passes all applicable filters.