220class Entity(EntityMixin, EntityProtocol):
221    """A default implementation of fully functional entity.
222
223    ```python
224    elements = [
225        Entity(id="cust-001", name="Alice Chen", metadata={"type": "customer"}),
226        Entity(id="cust-002", name="Bob Gupta", metadata={"type": "customer"}),
227        Entity(id="pros-003", name="Dana Rivera", metadata={"type": "prospect"}),
228    ]
229    boundaries = [
230        Entity(id="seg-enterprise", name="Enterprise Segment", metadata={"region": "NA"}),
231        Entity(id="seg-smb", name="SMB Segment", metadata={"region": "EMEA"}),
232        Entity(id="seg-dormant", name="Flight Risk", metadata={"status": "inactive", "last login": "2024-06-01"}),
233        Entity(id="seg-prospect", name="Active Prospects", metadata={"status": "demo given"})
234    ]
235
236    for e in elements:
237        print(f"Element: {e.summary()}")
238
239    for b in boundaries:
240        print(f"Boundary: {b.summary()}")
241    ```
242    """
243    __slots__ = ("_id", "_name", "_metadata")
244
245    # noinspection PyProtocol
246    def __init__(self, id: Optional[str] = None, name: Optional[str] = None, metadata: Optional[Dict[str, Any]] = None):
247        self._id: str = id or str(uuid.uuid4())
248        self._name: str = name or self.id
249        self._metadata: Dict[str, Any] = metadata or {}
250
251    @property
252    def id(self) -> str:
253        return self._id
254
255    # noinspection PyProtocol
256    @property
257    def name(self) -> str:
258        return self._name
259
260    @name.setter
261    def name(self, name: str) -> None:
262        self._name = name
263
264    @property
265    def metadata(self) -> Dict[str, Any]:
266        return self._metadata
267
268    def __str__(self) -> str:
269        return self.summary()

105@runtime_checkable
106class EntityProtocol(Protocol):
107    """
108    The interface contract for a domain entity to participate in a presence assertion.
109
110    Each entity requires only a unique identifier, a user-facing name.
111
112    Optional metadata may be provided and exposes specific attributes of the domain
113    entities that are relevant when interpreting or manipulating the results
114    of an analysis using the machinery of the calculus.
115
116    See `Entity` for an example of a concrete implementation.
117    """
118    __init__ = None  # type: ignore
119
120    @property
121    def id(self) -> str:
122        """
123        A stable, unique identifier for the entity.
124        Used for indexing and identity.
125        Defaults to a uuid.uuid4().
126        """
127        ...
128
129    @property
130    def name(self) -> str:
131        """
132        A user facing name for the entity, defaults to the id if None.
133        """
134        ...
135
136    @name.setter
137    def name(self, name: str) -> None:
138        """Setter for name"""
139        ...
140
141    @property
142    def metadata(self) -> Dict[str, Any]:
143        """
144        Optional extensible key-value metadata.
145        """
146        ...

381@dataclass(frozen=True)
382class PresenceAssertion:
383    """
384
385    This is the fundamental, immutable construct of The presence calculus,
386    and asserts the presence of an element at a boundary over a continuous interval of time.
387
388    A presence is defined over a half-open interval $[t_0, t_1)$ on the real
389    line, where $t_0$ is the onset time and $t_1$ is the reset time.
390
391    The
392    following constraints must hold:
393
394    - $t_0 < t_1$
395    - $t_0 \\in \\mathbb{R} \\cup \\{-\\infty\\}$
396    - $t_1 \\in \\mathbb{R} \\cup \\{+\\infty\\}$
397    - $t_0 \\ne +\\infty$
398    - $t_1 \\ne -\\infty$
399
400    These rules ensure that the interval is well-formed, bounded on the left,
401    and open on the right. Intervals such as $[2.0, 5.0)$, $[-\\infty, 4.2)$,
402    and $[1.0, +\\infty)$ are allowed, as are the special case $[-\\infty,
403    +\\infty)$ and $[0,0),$ the empty presence.
404
405    With the empty presence as the only exception, intervals with zero or negative duration, or with reversed or
406    undefined bounds, are disallowed.
407    """
408    element: Optional[EntityProtocol]
409    boundary: Optional[EntityProtocol]
410    onset_time: float
411    reset_time: float
412    presence: Optional[PresenceProtocol] = None
413    observer: Optional[EntityProtocol] | str = "observed"
414    assert_time: Optional[float] = 0.0
415
416    def __post_init__(self):
417        """
418        Validates the temporal bounds of the presence interval
419        """
420        if self.onset_time >= self.reset_time:
421            if not (self.onset_time == self.reset_time == 0):
422                raise ValueError(
423                    f"Invalid interval: onset_time ({self.onset_time}) must be less than reset_time ({self.reset_time})")
424
425        if self.onset_time == float("inf"):
426            raise ValueError("Presence cannot begin at +inf")
427
428        if self.reset_time == float("-inf"):
429            raise ValueError("Presence cannot end at -inf")
430
431    def overlaps(self, t0: float, t1: float) -> bool:
432        return self.reset_time > t0 and self.onset_time < t1
433
434    def mass(self) -> float:
435        """
436        Returns the mass of the presence.
437
438
439        
440        """
441        onset = max(0.0, self.onset_time)
442        return max(0.0, self.reset_time - onset)
443
444    def mass_contribution(self, t0: float, t1: float) -> float:
445        if t0 >= t1 or not self.overlaps(t0, t1):
446            return 0.0
447        start = max(self.onset_time, t0)
448        end = min(self.reset_time, t1)
449        return max(0.0, end - start)
450
451    def __str__(self) -> str:
452        element_str = str(self.element) if self.element is not None else "None"
453        boundary_str = str(self.boundary) if self.boundary is not None else "None"
454        interval_str = f"[{self.onset_time}, {self.reset_time})"
455        return (
456            f"Presence(element={element_str}, boundary={boundary_str}, "
457            f"interval={interval_str}, provenance={self.observer})"
458        )

 76class TimeModel:
 77
 78
 79    def __init__(self, origin: datetime, unit: CalendarUnit = "seconds"):
 80        self.origin = origin
 81        self.unit = unit
 82
 83    def to_float(self, t: datetime) -> float:
 84        delta = t - self.origin
 85        seconds = delta.total_seconds()
 86
 87        if self.unit == "seconds":
 88            return seconds
 89        if self.unit == "minutes":
 90            return seconds / 60.0
 91        if self.unit == "hours":
 92            return seconds / 3600.0
 93        if self.unit == "days":
 94            return delta.days + (delta.seconds / 86400.0)
 95        if self.unit == "months":
 96            return self._months_between(self.origin, t)
 97        if self.unit == "quarters":
 98            return self._months_between(self.origin, t) / 3.0
 99        if self.unit == "years":
100            return self._months_between(self.origin, t) / 12.0
101
102        raise ValueError(f"Unsupported time unit: {self.unit}")
103
104    def from_float(self, t: float) -> datetime:
105        if self.unit == "seconds":
106            return self.origin + timedelta(seconds=t)
107        if self.unit == "minutes":
108            return self.origin + timedelta(minutes=t)
109        if self.unit == "hours":
110            return self.origin + timedelta(hours=t)
111        if self.unit == "days":
112            return self.origin + timedelta(days=t)
113        if self.unit in {"months", "quarters", "years"}:
114            months = {
115                "months": int(round(t)),
116                "quarters": int(round(t * 3)),
117                "years": int(round(t * 12)),
118            }[self.unit]
119            return self.origin + relativedelta(months=+months)
120
121        raise ValueError(f"Unsupported time unit: {self.unit}")
122
123    @staticmethod
124    def _months_between(d1: datetime, d2: datetime) -> float:
125        """Return the number of calendar months between two dates, fractional."""
126        rd = relativedelta(d2, d1)
127        return rd.years * 12 + rd.months + (rd.days / 30.0)

 79class BasisTopology:
 80    """
 81    The foundational topology generated by a set of presence assertions.
 82
 83    Presences are treated as basis elements defining basic open sets.
 84    Internally, presences are grouped into sorted open covers per (element, boundary)
 85    and exposed through join, closure, and overlap operations.
 86    """
 87
 88    def __init__(self, presences: Iterable[PresenceAssertion]) -> None:
 89        """
 90        Initializes the topology from a set of presences.
 91
 92        Internally maintains a SortedSet for each (element, boundary) pair,
 93        ordered by onset_time for efficient merge and overlap operations.
 94        """
 95        self.cover_index: dict[Tuple, SortedSet[PresenceAssertion]] = defaultdict(
 96            lambda: SortedSet(key=presence_sort_key)
 97        )
 98
 99        for p in presences:
100            key = (p.element, p.boundary)
101            self.cover_index[key].add(p)
102
103    def get_cover(self, element, boundary) -> SortedSet[PresenceAssertion]:
104        """
105        Returns the open cover for a given (element, boundary) pair.
106        """
107        return self.cover_index.get((element, boundary), SortedSet(key=presence_sort_key))
108
109    @staticmethod
110    def join(p1: PresenceAssertion, p2: PresenceAssertion) -> PresenceAssertion:
111        """
112        Returns the join of two basis elements if they overlap or touch in time.
113        Returns EMPTY_PRESENCE if the presences are disjoint or incompatible.
114        """
115        if (p1.element, p1.boundary) != (p2.element, p2.boundary):
116            return EMPTY_PRESENCE
117
118        if p1.reset_time < p2.onset_time != float("-inf") and p1.reset_time != float("inf"):
119            return EMPTY_PRESENCE
120        if p2.reset_time < p1.onset_time != float("-inf") and p2.reset_time != float("inf"):
121            return EMPTY_PRESENCE
122
123        return PresenceAssertion(
124            element=p1.element,
125            boundary=p1.boundary,
126            onset_time=min(p1.onset_time, p2.onset_time),
127            reset_time=max(p1.reset_time, p2.reset_time),
128            observer="join",
129        )
130
131    def closure(self) -> set[PresenceAssertion]:
132        """
133        Computes the closure under join for each cover.
134
135        Returns a deduplicated set of merged presences that cover the same regions
136        as the original topology, but without adjacent overlaps.
137        """
138        closed = set()
139
140        for key, cover in self.cover_index.items():
141            merged_cover = []
142            for p in cover:
143                if not merged_cover:
144                    merged_cover.append(p)
145                    continue
146
147                last = merged_cover[-1]
148                j = self.join(last, p)
149
150                if j is not EMPTY_PRESENCE:
151                    merged_cover[-1] = j
152                else:
153                    merged_cover.append(p)
154
155            closed.update(merged_cover)
156
157        return closed
158
159    def find_overlapping(self, presence: PresenceAssertion) -> list[PresenceAssertion]:
160        """
161        Finds all presences in the same cover that overlap with the given presence.
162
163        This is a linear scan from the first potentially overlapping point onward,
164        relying on the sorted order of onset_time.
165        """
166        key = (presence.element, presence.boundary)
167        cover = self.cover_index.get(key, SortedSet(key=presence_sort_key))
168        overlapping = []
169
170        for p in cover.irange(minimum=None, maximum=None):
171            if p.onset_time >= presence.reset_time:
172                break
173            if p.reset_time > presence.onset_time:
174                overlapping.append(p)
175
176        return overlapping
177
178    def __iter__(self):
179        for cover in self.cover_index.values():
180            yield from cover

11class PresenceInvariant:
12    """
13    Computes the components of the Presence Invariant directly from a BasisTopology.
14
15    This invariant expresses a local conservation law of presence mass over any finite
16    time interval [t0, t1), using only the closure of the topology.
17    """
18
19    def __init__(self, topology: BasisTopology):
20        self.topology = topology
21        self.closed_presences = topology.closure()
22
23    def _filter_window(self, t0: float, t1: float) -> list[PresenceAssertion]:
24        return [
25            p for p in self.closed_presences
26            if p.overlaps(t0,t1)
27        ]
28
29    def get_presence_summary(self, t0: float, t1: float) -> Tuple[float, int, float]:
30        """
31        Computes:
32        - Total presence mass A
33        - Number of overlapping presences N
34        - Interval length T
35        """
36        if t0 >= t1:
37            return 0.0, 0, 0.0
38
39        A = 0.0
40        N = 0
41        T = t1 - t0
42
43        for p in self._filter_window(t0, t1):
44            r = p.mass_contribution(t0, t1)
45            if r > 0.0:
46                A += r
47                N += 1
48
49        return A, N, T
50
51    def avg_presence_density(self, t0: float, t1: float) -> float:
52        A, _, T = self.get_presence_summary(t0, t1)
53        return A / T if T > 0 else 0.0
54
55    def incidence_rate(self, t0: float, t1: float) -> float:
56        _, N, T = self.get_presence_summary(t0, t1)
57        return N / T if T > 0 else 0.0
58
59
60    def avg_presence_mass(self, t0: float, t1: float) -> float:
61        A, N, _ = self.get_presence_summary(t0, t1)
62        return A / N if N > 0 else 0.0
63
64    def invariant(self, t0: float, t1: float) -> Tuple[float, float, float]:
65        """
66        Returns:
67            (avg_presence_density, incidence_rate, avg_presence_mass)
68
69        These satisfy the Presence Invariant:
70            avg_presence_density = incidence_rate × avg_presence_mass
71        """
72        A, N, T = self.get_presence_summary(t0, t1)
73        L = A / T if T > 0 else 0.0
74        Λ = N / T if T > 0 else 0.0
75        w = A / N if N > 0 else 0.0
76        return L, Λ, w

 13@dataclass
 14class Timescale:
 15    """
 16    Timescale represents a partitioning of a continuous time interval [t0, t1)
 17    into N = ceil((t1 - t0) / bin_width) contiguous, left-aligned, non-overlapping bins.
 18
 19    Each bin has width `bin_width` and covers a half-open interval:
 20        Bin k = [t0 + k * bin_width, t0 + (k + 1) * bin_width)
 21
 22    This class provides methods for:
 23    - Mapping real-valued timestamps to discrete bin indices
 24    - Extracting the time boundaries of any bin
 25    - Computing which bins an interval [start, end) overlaps
 26    - Estimating how much of a bin is covered by a given interval
 27
 28    **Boundary Behavior**:
 29    - All bins lie strictly within [t0, t1)
 30    - Any time `t` where t < t0 or t >= t1 is considered **outside** the defined timescale
 31    - bin_index(t) may return an out-of-range index if `t < t0` or `t >= t1`
 32
 33    This class does not perform clipping: it assumes all inputs are in-range unless explicitly clipped by the caller.
 34"""
 35
 36    t0: float
 37    """start time of the interval [t0, t1)"""
 38    t1: float
 39    """end time of the interval [t0, t1)"""
 40
 41    bin_width: float
 42    """Width of each bin"""
 43
 44    @property
 45    def num_bins(self) -> int:
 46        """Return number of bins between t0 and t1."""
 47        return int(np.ceil((self.t1 - self.t0) / self.bin_width))
 48
 49    # Mapping from continuous time to discrete bins.
 50    def bin_index(self, time: float) -> int:
 51        """Purpose:
 52            Map a real-valued timestamp to the index of the bin that contains it.
 53
 54        Contract:
 55            Returns k such that bin_start(k) ≤ time < bin_end(k)
 56            Uses floor() logic — i.e., left-aligned binning
 57            No bounds check: time < t0 may yield negative indices; time ≥ t1 may return out-of-bounds indices
 58            Caller is responsible for ensuring t0 ≤ time < t1 if range enforcement is needed
 59        """
 60        return int(np.floor((time - self.t0) / self.bin_width))
 61
 62    def bin_slice(self, start: float, end: float) -> Tuple[int, int]:
 63        """Return the bin indices [start_bin, end_bin) that overlap the interval [start, end).
 64        Contract:
 65            - Clips the interval [start, end) to [t0, t1) before binning
 66            - Computes:
 67                start_bin = floor((clipped_start - t0) / bin_width)
 68                end_bin   = ceil((clipped_end   - t0) / bin_width)
 69            - Resulting slice [start_bin, end_bin) may be empty if the interval does not overlap the timescale
 70            - start_bin ∈ [0, num_bins)
 71            - end_bin   ∈ [0, num_bins]
 72
 73        """
 74        effective_start = max(start, self.t0)
 75        effective_end = min(end, self.t1)
 76        if effective_start >= effective_end:
 77            return 0, 0
 78        start_bin = int(np.floor((effective_start - self.t0) / self.bin_width))
 79        end_bin = int(np.ceil((effective_end - self.t0) / self.bin_width))
 80        return start_bin, end_bin
 81
 82    def fractional_overlap(self, start: float, end: float, bin_idx: int) -> float:
 83        """Return the fraction of the bin at index `bin_idx` that is covered by the interval [start, end).
 84        Contract:
 85            - Computes how much of bin_idx's interval is covered by [start, end)
 86            - Returns value in [0.0, 1.0] based on normalized overlap over bin width
 87            - Clipped to bin extent: overlaps outside the bin are ignored
 88            - Used to compute partial presence contribution within a bin
 89        """
 90        # Clip to timescale
 91        start = max(start, self.t0)
 92        end = min(end, self.t1)
 93
 94        bin_start = self.bin_start(bin_idx)
 95        bin_end = self.bin_end(bin_idx)
 96
 97        overlap_start = max(start, bin_start)
 98        overlap_end = min(end, bin_end)
 99
100        return max(0.0, overlap_end - overlap_start) / self.bin_width
101
102    # Mapping from discrete bins back to continuous time.
103    def bin_start(self, bin_idx: int) -> float:
104        """Return the start time of a bin given its index.
105        Contract:
106            bin_start(k) = t0 + k * bin_width
107        """
108        return self.t0 + bin_idx * self.bin_width
109
110    def bin_end(self, bin_idx: int) -> float:
111        """Return the end time of a bin given its index.
112        Contract:
113            bin_end(k) = t0 + (k + 1) * bin_width
114        """
115        return self.t0 + (bin_idx + 1) * self.bin_width
116
117    def bin_edges(self) -> np.ndarray:
118        """
119        Return an array of bin edge times from t0 to t1, spaced by bin_width.
120
121        The result has length `num_bins + 1` and is safe against floating-point rounding
122        by capping the range to include exactly the number of bins implied by `num_bins()`.
123
124        Contract:
125        - Returns `num_bins + 1` edge values such that:
126            edges = [t0, t0 + bin_width, ..., t1]
127
128        - Guarantees:
129            bin_start(k) == edges[k]
130            bin_end(k)   == edges[k + 1]
131
132        - Handles floating-point rounding safely:
133            If np.arange overproduces due to rounding, result is trimmed
134            to ensure exactly `num_bins + 1` entries.
135
136        This method defines the canonical bin boundaries used across
137        the presence matrix and all derived metrics.
138
139        Example:
140            Timescale(t0=0.0, t1=10.0, bin_width=2.0).bin_edges()
141            => array([0.0, 2.0, 4.0, 6.0, 8.0, 10.0])
142        """
143        num_edges = self.num_bins + 1
144        edges = np.arange(self.t0, self.t0 + num_edges * self.bin_width, self.bin_width)
145
146        # Ensure exactly num_edges (for safety in rare floating-point cases)
147        if len(edges) > num_edges:
148            edges = edges[:num_edges]
149        return edges
150
151
152    def time_range(self, bin_idx: int) -> Tuple[float, float]:
153        """
154            Return the (start, end) time of a bin.
155            Contract:
156                Returns tuple (bin_start(k), bin_end(k))
157                Matches exactly the continuous interval spanned by the bin
158        """
159        return self.bin_start(bin_idx), self.bin_end(bin_idx)