spark-kindling-ext-temporal 0.14.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- spark_kindling_ext_temporal-0.14.0/PKG-INFO +192 -0
- spark_kindling_ext_temporal-0.14.0/README.md +170 -0
- spark_kindling_ext_temporal-0.14.0/kindling_ext_temporal/__init__.py +118 -0
- spark_kindling_ext_temporal-0.14.0/kindling_ext_temporal/chain.py +601 -0
- spark_kindling_ext_temporal-0.14.0/kindling_ext_temporal/conditions.py +310 -0
- spark_kindling_ext_temporal-0.14.0/kindling_ext_temporal/engine.py +518 -0
- spark_kindling_ext_temporal-0.14.0/kindling_ext_temporal/entities.py +188 -0
- spark_kindling_ext_temporal-0.14.0/kindling_ext_temporal/registry.py +559 -0
- spark_kindling_ext_temporal-0.14.0/kindling_ext_temporal/translation.py +460 -0
- spark_kindling_ext_temporal-0.14.0/kindling_ext_temporal/validation.py +465 -0
- spark_kindling_ext_temporal-0.14.0/pyproject.toml +41 -0
- spark_kindling_ext_temporal-0.14.0/pyproject.toml.orig +38 -0
|
@@ -0,0 +1,192 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: spark-kindling-ext-temporal
|
|
3
|
+
Version: 0.14.0
|
|
4
|
+
Summary: Temporal event, condition, and episode primitives for Kindling
|
|
5
|
+
Author: SEP Engineering
|
|
6
|
+
Author-email: SEP Engineering <engineering@sep.com>
|
|
7
|
+
License-Expression: MIT
|
|
8
|
+
Classifier: Development Status :: 4 - Beta
|
|
9
|
+
Classifier: Intended Audience :: Developers
|
|
10
|
+
Classifier: Operating System :: OS Independent
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
13
|
+
Classifier: Topic :: Database
|
|
14
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
15
|
+
Requires-Dist: spark-kindling>=0.14.0,<0.15
|
|
16
|
+
Requires-Python: >=3.10
|
|
17
|
+
Project-URL: Homepage, https://github.com/sep/spark-kindling-framework
|
|
18
|
+
Project-URL: Documentation, https://github.com/sep/spark-kindling-framework/tree/main/docs
|
|
19
|
+
Project-URL: Changelog, https://github.com/sep/spark-kindling-framework/blob/main/CHANGELOG.md
|
|
20
|
+
Project-URL: Issues, https://github.com/sep/spark-kindling-framework/issues
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
|
|
23
|
+
# spark-kindling-ext-temporal
|
|
24
|
+
|
|
25
|
+
Temporal event, condition, and episode primitives for Kindling.
|
|
26
|
+
|
|
27
|
+
This package implements the first executable slice of the extension described
|
|
28
|
+
in `docs/proposals/temporal_event_segmentation.md`. It supports the core
|
|
29
|
+
Event -> Condition boundary Events -> closed Episode path, but it is not yet the
|
|
30
|
+
complete temporal-processing system described in the white paper and proposal.
|
|
31
|
+
|
|
32
|
+
Operator docs: the execution/streaming contract is specified in
|
|
33
|
+
`docs/guide/temporal_streaming_contract.md`; a worked telemetry-to-gold
|
|
34
|
+
walkthrough is in `docs/guide/temporal_end_to_end.md`.
|
|
35
|
+
|
|
36
|
+
## Installation
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
pip install spark-kindling-ext-temporal
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
In a uv project, `kindling env add spark-kindling-ext-temporal` pins the version that matches the
|
|
43
|
+
project's Kindling release.
|
|
44
|
+
|
|
45
|
+
## Implemented
|
|
46
|
+
|
|
47
|
+
- canonical `silver.events`, `silver.conditions`, and `silver.episodes` entity
|
|
48
|
+
metadata through a DI-overridable `TemporalEntityResolver`;
|
|
49
|
+
- `DataEvents` registration for base event normalizers and the generic
|
|
50
|
+
condition engine;
|
|
51
|
+
- `DataEpisodes` registration for event-pair episode definitions;
|
|
52
|
+
- base-event lowering into the canonical event envelope;
|
|
53
|
+
- `TemporalConditionValidator` for per-row `enter_when`/`exit_when` validation
|
|
54
|
+
and event-type graph generation/cycle checks;
|
|
55
|
+
- `ConditionEngineRunner` execution that emits `{condition_id}.entered` and
|
|
56
|
+
`{condition_id}.exited` events with incremented generation numbers;
|
|
57
|
+
- `EpisodeRunner` execution that pairs start/end events into closed episodes and
|
|
58
|
+
materializes open episodes when no end event has arrived;
|
|
59
|
+
- batch expiration of open episodes using `expires_after_seconds` and an
|
|
60
|
+
explicit evaluation time (execution parameter or
|
|
61
|
+
`kindling.temporal.evaluation_time` config) or bounded input horizon;
|
|
62
|
+
- bounded batch correction where a visible real end event wins over synthetic
|
|
63
|
+
expiration while preserving the same `episode_id`;
|
|
64
|
+
- episode invalidation for configured `min_duration_seconds` and
|
|
65
|
+
`max_duration_seconds` bounds, including synthetic invalidation of open
|
|
66
|
+
episodes that pass their maximum duration without a real end event; when
|
|
67
|
+
both expiration and max duration are configured, the earliest synthetic
|
|
68
|
+
boundary is terminal;
|
|
69
|
+
- episode-determination events emitted back into the canonical event envelope
|
|
70
|
+
with `correlation_id = episode_id` and incremented generation numbers,
|
|
71
|
+
including expiration events for expired episodes and invalidation events for
|
|
72
|
+
invalidated episodes;
|
|
73
|
+
- stateful late real-end revision of persisted episodes: the episode engine
|
|
74
|
+
resolves its own prior state at execution time (on by default, disabled via
|
|
75
|
+
`kindling.temporal.revise_persisted`), reconstructs start boundaries for
|
|
76
|
+
persisted open, expired, and synthetically-invalidated episodes, and
|
|
77
|
+
re-emits them with the same `episode_id` when a late real end event
|
|
78
|
+
arrives — the entity's `merge_columns=["episode_id"]` upsert turns the
|
|
79
|
+
re-emit into an in-place revision; a batch with no new events and no
|
|
80
|
+
evaluation time emits nothing for reconstructed episodes so persisted state
|
|
81
|
+
never regresses;
|
|
82
|
+
- validated conditions ingestion: `ingest_conditions` validates rule rows per
|
|
83
|
+
row (Spark SQL expression parsing, event-type graph cycle rejection,
|
|
84
|
+
duplicate `condition_id`s within a batch), quarantines rejects (returned,
|
|
85
|
+
and appended to
|
|
86
|
+
`kindling.temporal.conditions.quarantine_entity_id` when configured), and
|
|
87
|
+
upserts the well-formed rows — including disabled ones — through the
|
|
88
|
+
conditions entity's SCD2 merge; `validated_conditions_transform` gates a
|
|
89
|
+
`FileIngestion` file-drop entry with the same validation, rejecting a file
|
|
90
|
+
whole on any invalid row;
|
|
91
|
+
- unit, integration, and system coverage for the first executable slice,
|
|
92
|
+
including a Databricks system test (`tests/system/extensions/temporal/`,
|
|
93
|
+
`tests/data-apps/temporal-test-app`) that validates the end-to-end flow,
|
|
94
|
+
validated conditions ingestion with per-row quarantine, and cross-run
|
|
95
|
+
late-end revision (two separate job executions over shared catalog
|
|
96
|
+
storage) on a real workspace.
|
|
97
|
+
|
|
98
|
+
## Chained execution
|
|
99
|
+
|
|
100
|
+
`declare_temporal_chain()` (call it after all `DataEvents`/`DataEpisodes`
|
|
101
|
+
declarations) lowers the registered graph into two composite pipes that any
|
|
102
|
+
Kindling engine executes as ordinary pipes:
|
|
103
|
+
|
|
104
|
+
- `temporal.chain.events.<chainid>` — reads the base events' driving entities
|
|
105
|
+
(each watermarked independently) and the conditions current view; computes base
|
|
106
|
+
envelopes, condition boundary passes, and episode-determination events as
|
|
107
|
+
in-memory generation strata, feeding determination events back into
|
|
108
|
+
further condition passes until quiescence (capped by
|
|
109
|
+
`kindling.temporal.max_generations`); sole writer of the events entity.
|
|
110
|
+
- `temporal.chain.episodes.<chainid>` — reads the events entity
|
|
111
|
+
(watermarked); pairs boundaries per episode declaration against prior
|
|
112
|
+
state; sole writer of the episodes entity.
|
|
113
|
+
|
|
114
|
+
Compared with running the per-declaration pipes: higher-order conditions
|
|
115
|
+
converge in one run instead of one scheduled run per generation, the events
|
|
116
|
+
table has a single writer and no in-graph self-reads (the shape SDP/Lakeflow
|
|
117
|
+
engines require), only true boundary inputs carry watermark cursors, and
|
|
118
|
+
determination events derive from the same pre-revision prior state as the
|
|
119
|
+
episode rows. The per-declaration pipes remain registered and independently
|
|
120
|
+
executable; the chain is an alternative lowering over the same metadata.
|
|
121
|
+
Multi-source chains need no staging entity and no engine opt-in.
|
|
122
|
+
|
|
123
|
+
## Configuration
|
|
124
|
+
|
|
125
|
+
- `kindling.temporal.evaluation_time` — optional explicit evaluation time for
|
|
126
|
+
synthetic episode boundaries (expiration and max-duration invalidation) in
|
|
127
|
+
batch views. A per-execution `temporal_evaluation_time` keyword argument to
|
|
128
|
+
a temporal pipe's `execute` overrides it. When neither is set, the bounded
|
|
129
|
+
input horizon (the batch's maximum `event_ts`) is used.
|
|
130
|
+
- `kindling.temporal.revise_persisted` — set to `false` to disable the prior
|
|
131
|
+
episode-state read entirely; episode pipes then compute a pure batch view.
|
|
132
|
+
Defaults to enabled.
|
|
133
|
+
- `kindling.temporal.conditions.quarantine_entity_id` — optional entity id for
|
|
134
|
+
rejected condition rows; when set, `ingest_conditions` appends quarantined
|
|
135
|
+
rows (condition id, errors, raw row, timestamp) there. Unset: rejects are
|
|
136
|
+
only returned in the ingestion result.
|
|
137
|
+
- `kindling.temporal.max_generations` — cap on the chained lowering's
|
|
138
|
+
feedback iterations (default 10); the chain stops earlier on quiescence. A
|
|
139
|
+
per-execution `temporal_max_generations` keyword argument overrides it.
|
|
140
|
+
|
|
141
|
+
## Revision semantics
|
|
142
|
+
|
|
143
|
+
Episodes ended by a real end event are terminal: revision reconsiders only
|
|
144
|
+
persisted episodes whose end is synthetic (expired, invalidated past max
|
|
145
|
+
duration) or absent (open). A late-arriving end event that is earlier than an
|
|
146
|
+
already-accepted real end does not reopen or re-pair a closed episode. Prior
|
|
147
|
+
determination events (for example an expiration event later superseded by a
|
|
148
|
+
real close) remain in `silver.events` as history; the corrective event is
|
|
149
|
+
emitted alongside them with its own deterministic `event_id`.
|
|
150
|
+
|
|
151
|
+
Prior state is an execution-strategy concern this extension owns, not a
|
|
152
|
+
declared dataflow dependency: episode pipes declare only the events entity as
|
|
153
|
+
input, and the engine resolves persisted episode state itself at execution
|
|
154
|
+
time — a keyword argument named after the episodes entity (tests, manual
|
|
155
|
+
runs) wins, the `kindling.temporal.revise_persisted` config key can disable
|
|
156
|
+
the read, and otherwise the episodes entity is read through its provider when
|
|
157
|
+
it exists. A first run therefore proceeds with no prior state instead of
|
|
158
|
+
failing on a read of the table it is about to create. The pipes carry a
|
|
159
|
+
`temporal.reads_prior_state` tag so lineage tooling can see the feedback
|
|
160
|
+
loop the pipe graph deliberately does not schedule around. (A pipe that does
|
|
161
|
+
declare its own output as an input — the determination pipe writes and reads
|
|
162
|
+
`silver.events` — is prior-state feedback too; `PipeGraphBuilder` skips such
|
|
163
|
+
self-edges instead of reporting a cycle.)
|
|
164
|
+
|
|
165
|
+
Known limitations:
|
|
166
|
+
|
|
167
|
+
- episode rows persisted before the schema carried `start_generation` are
|
|
168
|
+
reconstructed at generation 1; determination events for that legacy cohort
|
|
169
|
+
can understate generation, and revision writes the fallback back to the
|
|
170
|
+
row;
|
|
171
|
+
- revision re-emits refresh `created_at` (the upsert updates all columns), so
|
|
172
|
+
a revised episode does not retain its original creation timestamp.
|
|
173
|
+
|
|
174
|
+
## Lifecycle identity
|
|
175
|
+
|
|
176
|
+
`episode_id` is deterministic from the episode definition and start boundary,
|
|
177
|
+
not from the eventual end boundary. That lets a materialized open episode keep
|
|
178
|
+
the same identity when a bounded batch view later marks it expired or closes it
|
|
179
|
+
with a real end event. End-boundary changes update lifecycle fields such as
|
|
180
|
+
`end_event_id`, `end_time`, `status`, `close_reason`, and `duration_ms`; they
|
|
181
|
+
do not create a different episode identity.
|
|
182
|
+
|
|
183
|
+
## Not yet implemented
|
|
184
|
+
|
|
185
|
+
- revision of episodes closed by a real end event (a later-arriving end
|
|
186
|
+
earlier than the accepted one never re-pairs a closed episode);
|
|
187
|
+
- late-event grace windows, watermarks, replay/backfill semantics, and
|
|
188
|
+
stateful streaming execution;
|
|
189
|
+
- multi-generation orchestration beyond one condition-engine pass;
|
|
190
|
+
- interval hierarchy and temporal-relation reasoning;
|
|
191
|
+
- aggregation, correlation, and inference-derived event paths;
|
|
192
|
+
- a `kindling conditions set/remove` CLI on top of `ingest_conditions`;
|
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
# spark-kindling-ext-temporal
|
|
2
|
+
|
|
3
|
+
Temporal event, condition, and episode primitives for Kindling.
|
|
4
|
+
|
|
5
|
+
This package implements the first executable slice of the extension described
|
|
6
|
+
in `docs/proposals/temporal_event_segmentation.md`. It supports the core
|
|
7
|
+
Event -> Condition boundary Events -> closed Episode path, but it is not yet the
|
|
8
|
+
complete temporal-processing system described in the white paper and proposal.
|
|
9
|
+
|
|
10
|
+
Operator docs: the execution/streaming contract is specified in
|
|
11
|
+
`docs/guide/temporal_streaming_contract.md`; a worked telemetry-to-gold
|
|
12
|
+
walkthrough is in `docs/guide/temporal_end_to_end.md`.
|
|
13
|
+
|
|
14
|
+
## Installation
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
pip install spark-kindling-ext-temporal
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
In a uv project, `kindling env add spark-kindling-ext-temporal` pins the version that matches the
|
|
21
|
+
project's Kindling release.
|
|
22
|
+
|
|
23
|
+
## Implemented
|
|
24
|
+
|
|
25
|
+
- canonical `silver.events`, `silver.conditions`, and `silver.episodes` entity
|
|
26
|
+
metadata through a DI-overridable `TemporalEntityResolver`;
|
|
27
|
+
- `DataEvents` registration for base event normalizers and the generic
|
|
28
|
+
condition engine;
|
|
29
|
+
- `DataEpisodes` registration for event-pair episode definitions;
|
|
30
|
+
- base-event lowering into the canonical event envelope;
|
|
31
|
+
- `TemporalConditionValidator` for per-row `enter_when`/`exit_when` validation
|
|
32
|
+
and event-type graph generation/cycle checks;
|
|
33
|
+
- `ConditionEngineRunner` execution that emits `{condition_id}.entered` and
|
|
34
|
+
`{condition_id}.exited` events with incremented generation numbers;
|
|
35
|
+
- `EpisodeRunner` execution that pairs start/end events into closed episodes and
|
|
36
|
+
materializes open episodes when no end event has arrived;
|
|
37
|
+
- batch expiration of open episodes using `expires_after_seconds` and an
|
|
38
|
+
explicit evaluation time (execution parameter or
|
|
39
|
+
`kindling.temporal.evaluation_time` config) or bounded input horizon;
|
|
40
|
+
- bounded batch correction where a visible real end event wins over synthetic
|
|
41
|
+
expiration while preserving the same `episode_id`;
|
|
42
|
+
- episode invalidation for configured `min_duration_seconds` and
|
|
43
|
+
`max_duration_seconds` bounds, including synthetic invalidation of open
|
|
44
|
+
episodes that pass their maximum duration without a real end event; when
|
|
45
|
+
both expiration and max duration are configured, the earliest synthetic
|
|
46
|
+
boundary is terminal;
|
|
47
|
+
- episode-determination events emitted back into the canonical event envelope
|
|
48
|
+
with `correlation_id = episode_id` and incremented generation numbers,
|
|
49
|
+
including expiration events for expired episodes and invalidation events for
|
|
50
|
+
invalidated episodes;
|
|
51
|
+
- stateful late real-end revision of persisted episodes: the episode engine
|
|
52
|
+
resolves its own prior state at execution time (on by default, disabled via
|
|
53
|
+
`kindling.temporal.revise_persisted`), reconstructs start boundaries for
|
|
54
|
+
persisted open, expired, and synthetically-invalidated episodes, and
|
|
55
|
+
re-emits them with the same `episode_id` when a late real end event
|
|
56
|
+
arrives — the entity's `merge_columns=["episode_id"]` upsert turns the
|
|
57
|
+
re-emit into an in-place revision; a batch with no new events and no
|
|
58
|
+
evaluation time emits nothing for reconstructed episodes so persisted state
|
|
59
|
+
never regresses;
|
|
60
|
+
- validated conditions ingestion: `ingest_conditions` validates rule rows per
|
|
61
|
+
row (Spark SQL expression parsing, event-type graph cycle rejection,
|
|
62
|
+
duplicate `condition_id`s within a batch), quarantines rejects (returned,
|
|
63
|
+
and appended to
|
|
64
|
+
`kindling.temporal.conditions.quarantine_entity_id` when configured), and
|
|
65
|
+
upserts the well-formed rows — including disabled ones — through the
|
|
66
|
+
conditions entity's SCD2 merge; `validated_conditions_transform` gates a
|
|
67
|
+
`FileIngestion` file-drop entry with the same validation, rejecting a file
|
|
68
|
+
whole on any invalid row;
|
|
69
|
+
- unit, integration, and system coverage for the first executable slice,
|
|
70
|
+
including a Databricks system test (`tests/system/extensions/temporal/`,
|
|
71
|
+
`tests/data-apps/temporal-test-app`) that validates the end-to-end flow,
|
|
72
|
+
validated conditions ingestion with per-row quarantine, and cross-run
|
|
73
|
+
late-end revision (two separate job executions over shared catalog
|
|
74
|
+
storage) on a real workspace.
|
|
75
|
+
|
|
76
|
+
## Chained execution
|
|
77
|
+
|
|
78
|
+
`declare_temporal_chain()` (call it after all `DataEvents`/`DataEpisodes`
|
|
79
|
+
declarations) lowers the registered graph into two composite pipes that any
|
|
80
|
+
Kindling engine executes as ordinary pipes:
|
|
81
|
+
|
|
82
|
+
- `temporal.chain.events.<chainid>` — reads the base events' driving entities
|
|
83
|
+
(each watermarked independently) and the conditions current view; computes base
|
|
84
|
+
envelopes, condition boundary passes, and episode-determination events as
|
|
85
|
+
in-memory generation strata, feeding determination events back into
|
|
86
|
+
further condition passes until quiescence (capped by
|
|
87
|
+
`kindling.temporal.max_generations`); sole writer of the events entity.
|
|
88
|
+
- `temporal.chain.episodes.<chainid>` — reads the events entity
|
|
89
|
+
(watermarked); pairs boundaries per episode declaration against prior
|
|
90
|
+
state; sole writer of the episodes entity.
|
|
91
|
+
|
|
92
|
+
Compared with running the per-declaration pipes: higher-order conditions
|
|
93
|
+
converge in one run instead of one scheduled run per generation, the events
|
|
94
|
+
table has a single writer and no in-graph self-reads (the shape SDP/Lakeflow
|
|
95
|
+
engines require), only true boundary inputs carry watermark cursors, and
|
|
96
|
+
determination events derive from the same pre-revision prior state as the
|
|
97
|
+
episode rows. The per-declaration pipes remain registered and independently
|
|
98
|
+
executable; the chain is an alternative lowering over the same metadata.
|
|
99
|
+
Multi-source chains need no staging entity and no engine opt-in.
|
|
100
|
+
|
|
101
|
+
## Configuration
|
|
102
|
+
|
|
103
|
+
- `kindling.temporal.evaluation_time` — optional explicit evaluation time for
|
|
104
|
+
synthetic episode boundaries (expiration and max-duration invalidation) in
|
|
105
|
+
batch views. A per-execution `temporal_evaluation_time` keyword argument to
|
|
106
|
+
a temporal pipe's `execute` overrides it. When neither is set, the bounded
|
|
107
|
+
input horizon (the batch's maximum `event_ts`) is used.
|
|
108
|
+
- `kindling.temporal.revise_persisted` — set to `false` to disable the prior
|
|
109
|
+
episode-state read entirely; episode pipes then compute a pure batch view.
|
|
110
|
+
Defaults to enabled.
|
|
111
|
+
- `kindling.temporal.conditions.quarantine_entity_id` — optional entity id for
|
|
112
|
+
rejected condition rows; when set, `ingest_conditions` appends quarantined
|
|
113
|
+
rows (condition id, errors, raw row, timestamp) there. Unset: rejects are
|
|
114
|
+
only returned in the ingestion result.
|
|
115
|
+
- `kindling.temporal.max_generations` — cap on the chained lowering's
|
|
116
|
+
feedback iterations (default 10); the chain stops earlier on quiescence. A
|
|
117
|
+
per-execution `temporal_max_generations` keyword argument overrides it.
|
|
118
|
+
|
|
119
|
+
## Revision semantics
|
|
120
|
+
|
|
121
|
+
Episodes ended by a real end event are terminal: revision reconsiders only
|
|
122
|
+
persisted episodes whose end is synthetic (expired, invalidated past max
|
|
123
|
+
duration) or absent (open). A late-arriving end event that is earlier than an
|
|
124
|
+
already-accepted real end does not reopen or re-pair a closed episode. Prior
|
|
125
|
+
determination events (for example an expiration event later superseded by a
|
|
126
|
+
real close) remain in `silver.events` as history; the corrective event is
|
|
127
|
+
emitted alongside them with its own deterministic `event_id`.
|
|
128
|
+
|
|
129
|
+
Prior state is an execution-strategy concern this extension owns, not a
|
|
130
|
+
declared dataflow dependency: episode pipes declare only the events entity as
|
|
131
|
+
input, and the engine resolves persisted episode state itself at execution
|
|
132
|
+
time — a keyword argument named after the episodes entity (tests, manual
|
|
133
|
+
runs) wins, the `kindling.temporal.revise_persisted` config key can disable
|
|
134
|
+
the read, and otherwise the episodes entity is read through its provider when
|
|
135
|
+
it exists. A first run therefore proceeds with no prior state instead of
|
|
136
|
+
failing on a read of the table it is about to create. The pipes carry a
|
|
137
|
+
`temporal.reads_prior_state` tag so lineage tooling can see the feedback
|
|
138
|
+
loop the pipe graph deliberately does not schedule around. (A pipe that does
|
|
139
|
+
declare its own output as an input — the determination pipe writes and reads
|
|
140
|
+
`silver.events` — is prior-state feedback too; `PipeGraphBuilder` skips such
|
|
141
|
+
self-edges instead of reporting a cycle.)
|
|
142
|
+
|
|
143
|
+
Known limitations:
|
|
144
|
+
|
|
145
|
+
- episode rows persisted before the schema carried `start_generation` are
|
|
146
|
+
reconstructed at generation 1; determination events for that legacy cohort
|
|
147
|
+
can understate generation, and revision writes the fallback back to the
|
|
148
|
+
row;
|
|
149
|
+
- revision re-emits refresh `created_at` (the upsert updates all columns), so
|
|
150
|
+
a revised episode does not retain its original creation timestamp.
|
|
151
|
+
|
|
152
|
+
## Lifecycle identity
|
|
153
|
+
|
|
154
|
+
`episode_id` is deterministic from the episode definition and start boundary,
|
|
155
|
+
not from the eventual end boundary. That lets a materialized open episode keep
|
|
156
|
+
the same identity when a bounded batch view later marks it expired or closes it
|
|
157
|
+
with a real end event. End-boundary changes update lifecycle fields such as
|
|
158
|
+
`end_event_id`, `end_time`, `status`, `close_reason`, and `duration_ms`; they
|
|
159
|
+
do not create a different episode identity.
|
|
160
|
+
|
|
161
|
+
## Not yet implemented
|
|
162
|
+
|
|
163
|
+
- revision of episodes closed by a real end event (a later-arriving end
|
|
164
|
+
earlier than the accepted one never re-pairs a closed episode);
|
|
165
|
+
- late-event grace windows, watermarks, replay/backfill semantics, and
|
|
166
|
+
stateful streaming execution;
|
|
167
|
+
- multi-generation orchestration beyond one condition-engine pass;
|
|
168
|
+
- interval hierarchy and temporal-relation reasoning;
|
|
169
|
+
- aggregation, correlation, and inference-derived event paths;
|
|
170
|
+
- a `kindling conditions set/remove` CLI on top of `ingest_conditions`;
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
"""Temporal event, condition, and episode primitives for Kindling."""
|
|
2
|
+
|
|
3
|
+
from .chain import (
|
|
4
|
+
AUTOCOLLAPSE_CONFIG_KEY,
|
|
5
|
+
MAX_GENERATIONS_CONFIG_KEY,
|
|
6
|
+
chain_episodes_pipe_id,
|
|
7
|
+
chain_events_pipe_id,
|
|
8
|
+
collapse_temporal_chain,
|
|
9
|
+
declare_temporal_chain,
|
|
10
|
+
)
|
|
11
|
+
from .conditions import (
|
|
12
|
+
QUARANTINE_ENTITY_CONFIG_KEY,
|
|
13
|
+
ConditionsIngestionResult,
|
|
14
|
+
ingest_conditions,
|
|
15
|
+
validated_conditions_transform,
|
|
16
|
+
)
|
|
17
|
+
from .engine import ConditionEngineRunner, EpisodeRunner
|
|
18
|
+
from .entities import (
|
|
19
|
+
SimpleTemporalEntityResolver,
|
|
20
|
+
TemporalEntityResolver,
|
|
21
|
+
condition_quarantine_schema,
|
|
22
|
+
conditions_entity_schema,
|
|
23
|
+
conditions_schema,
|
|
24
|
+
episodes_schema,
|
|
25
|
+
events_schema,
|
|
26
|
+
)
|
|
27
|
+
from .registry import (
|
|
28
|
+
BaseEventMetadata,
|
|
29
|
+
ConditionEngineMetadata,
|
|
30
|
+
DataConditions,
|
|
31
|
+
DataEpisodes,
|
|
32
|
+
DataEvents,
|
|
33
|
+
EpisodeMetadata,
|
|
34
|
+
TemporalConditionRegistry,
|
|
35
|
+
TemporalConditionRegistryManager,
|
|
36
|
+
TemporalEpisodeRegistry,
|
|
37
|
+
TemporalEpisodeRegistryManager,
|
|
38
|
+
TemporalEventRegistry,
|
|
39
|
+
TemporalEventRegistryManager,
|
|
40
|
+
)
|
|
41
|
+
from .translation import (
|
|
42
|
+
TEMPORAL_LOWERING_CHAIN,
|
|
43
|
+
TEMPORAL_LOWERING_DECLARED,
|
|
44
|
+
TEMPORAL_LOWERING_TAG,
|
|
45
|
+
TemporalPipeTranslator,
|
|
46
|
+
)
|
|
47
|
+
from .validation import (
|
|
48
|
+
ActiveSparkSqlExpressionParser,
|
|
49
|
+
ConditionRule,
|
|
50
|
+
ConditionValidationError,
|
|
51
|
+
ConditionValidationReport,
|
|
52
|
+
InvalidCondition,
|
|
53
|
+
TemporalConditionValidator,
|
|
54
|
+
)
|
|
55
|
+
|
|
56
|
+
__all__ = [
|
|
57
|
+
"ActiveSparkSqlExpressionParser",
|
|
58
|
+
"AUTOCOLLAPSE_CONFIG_KEY",
|
|
59
|
+
"BaseEventMetadata",
|
|
60
|
+
"MAX_GENERATIONS_CONFIG_KEY",
|
|
61
|
+
"chain_episodes_pipe_id",
|
|
62
|
+
"chain_events_pipe_id",
|
|
63
|
+
"collapse_temporal_chain",
|
|
64
|
+
"conditions_entity_schema",
|
|
65
|
+
"declare_temporal_chain",
|
|
66
|
+
"ConditionEngineRunner",
|
|
67
|
+
"ConditionEngineMetadata",
|
|
68
|
+
"ConditionRule",
|
|
69
|
+
"ConditionValidationError",
|
|
70
|
+
"ConditionValidationReport",
|
|
71
|
+
"ConditionsIngestionResult",
|
|
72
|
+
"QUARANTINE_ENTITY_CONFIG_KEY",
|
|
73
|
+
"DataConditions",
|
|
74
|
+
"DataEpisodes",
|
|
75
|
+
"DataEvents",
|
|
76
|
+
"EpisodeMetadata",
|
|
77
|
+
"EpisodeRunner",
|
|
78
|
+
"InvalidCondition",
|
|
79
|
+
"SimpleTemporalEntityResolver",
|
|
80
|
+
"TEMPORAL_LOWERING_CHAIN",
|
|
81
|
+
"TEMPORAL_LOWERING_DECLARED",
|
|
82
|
+
"TEMPORAL_LOWERING_TAG",
|
|
83
|
+
"TemporalConditionRegistry",
|
|
84
|
+
"TemporalConditionRegistryManager",
|
|
85
|
+
"TemporalConditionValidator",
|
|
86
|
+
"TemporalEntityResolver",
|
|
87
|
+
"TemporalEpisodeRegistry",
|
|
88
|
+
"TemporalEpisodeRegistryManager",
|
|
89
|
+
"TemporalEventRegistry",
|
|
90
|
+
"TemporalEventRegistryManager",
|
|
91
|
+
"TemporalPipeTranslator",
|
|
92
|
+
"condition_quarantine_schema",
|
|
93
|
+
"conditions_schema",
|
|
94
|
+
"episodes_schema",
|
|
95
|
+
"events_schema",
|
|
96
|
+
"ingest_conditions",
|
|
97
|
+
"validated_conditions_transform",
|
|
98
|
+
]
|
|
99
|
+
|
|
100
|
+
__version__ = "0.14.0"
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
def _register_services():
|
|
104
|
+
"""Register extension services with Kindling's DI container."""
|
|
105
|
+
from injector import singleton
|
|
106
|
+
from kindling.injection import GlobalInjector
|
|
107
|
+
|
|
108
|
+
injector = GlobalInjector.get_injector()
|
|
109
|
+
injector.binder.bind(TemporalEventRegistry, to=TemporalEventRegistryManager, scope=singleton)
|
|
110
|
+
injector.binder.bind(
|
|
111
|
+
TemporalEpisodeRegistry, to=TemporalEpisodeRegistryManager, scope=singleton
|
|
112
|
+
)
|
|
113
|
+
injector.binder.bind(
|
|
114
|
+
TemporalConditionRegistry, to=TemporalConditionRegistryManager, scope=singleton
|
|
115
|
+
)
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
_register_services()
|