terrine 0.1.0.dev0__py3-none-any.whl

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.
Files changed (144) hide show
  1. terrine/__init__.py +120 -0
  2. terrine/_time.py +21 -0
  3. terrine/adapters/__init__.py +3 -0
  4. terrine/adapters/increment.py +365 -0
  5. terrine/adapters/opentelemetry.py +63 -0
  6. terrine/agent/__init__.py +6 -0
  7. terrine/agent/definitions.py +143 -0
  8. terrine/agent/design_schema.py +220 -0
  9. terrine/agent/policy.py +144 -0
  10. terrine/agent/schemas.py +285 -0
  11. terrine/agent/tools.py +956 -0
  12. terrine/backends/__init__.py +3 -0
  13. terrine/backends/capabilities.py +117 -0
  14. terrine/backends/dialect.py +55 -0
  15. terrine/backends/extrema.py +40 -0
  16. terrine/backends/joins.py +75 -0
  17. terrine/backends/numeric.py +657 -0
  18. terrine/backends/sequences.py +40 -0
  19. terrine/backends/timestamps.py +421 -0
  20. terrine/compile/__init__.py +3 -0
  21. terrine/compile/_asof.py +165 -0
  22. terrine/compile/_predicates.py +110 -0
  23. terrine/compile/anchors.py +492 -0
  24. terrine/compile/columns.py +1353 -0
  25. terrine/compile/cost.py +110 -0
  26. terrine/compile/dispatch.py +148 -0
  27. terrine/compile/layers.py +242 -0
  28. terrine/compile/materialize.py +91 -0
  29. terrine/compile/provenance.py +120 -0
  30. terrine/compile/ranges.py +91 -0
  31. terrine/compile/retention.py +127 -0
  32. terrine/compile/shapes/__init__.py +3 -0
  33. terrine/compile/shapes/_observations.py +502 -0
  34. terrine/compile/shapes/calendar_comparison.py +370 -0
  35. terrine/compile/shapes/cohorts.py +285 -0
  36. terrine/compile/shapes/event_panel.py +46 -0
  37. terrine/compile/shapes/event_sequence.py +498 -0
  38. terrine/compile/shapes/life_table.py +244 -0
  39. terrine/compile/shapes/ltv.py +287 -0
  40. terrine/compile/shapes/matched_t0.py +75 -0
  41. terrine/compile/shapes/sequential.py +320 -0
  42. terrine/compile/shapes/state_panel.py +460 -0
  43. terrine/compile/shapes/time_to_event.py +521 -0
  44. terrine/data.py +1311 -0
  45. terrine/dataset/__init__.py +5 -0
  46. terrine/dataset/export.py +463 -0
  47. terrine/dataset/manifest.py +254 -0
  48. terrine/dataset/reference.py +582 -0
  49. terrine/dataset/splits.py +373 -0
  50. terrine/dataset/training.py +114 -0
  51. terrine/dataset/transforms.py +182 -0
  52. terrine/errors.py +98 -0
  53. terrine/execution/__init__.py +5 -0
  54. terrine/execution/_bigquery.py +318 -0
  55. terrine/execution/_metadata.py +47 -0
  56. terrine/execution/_native.py +574 -0
  57. terrine/execution/_postgres.py +468 -0
  58. terrine/execution/_publish.py +299 -0
  59. terrine/execution/_snowflake.py +684 -0
  60. terrine/execution/backend.py +349 -0
  61. terrine/execution/gates.py +90 -0
  62. terrine/execution/inputs.py +923 -0
  63. terrine/export/__init__.py +31 -0
  64. terrine/export/diff_diff.py +177 -0
  65. terrine/export/lifelines.py +219 -0
  66. terrine/export/preflight.py +243 -0
  67. terrine/export/surrogate.py +168 -0
  68. terrine/frame.py +1042 -0
  69. terrine/model.py +397 -0
  70. terrine/orchestration/__init__.py +3 -0
  71. terrine/orchestration/airflow.py +115 -0
  72. terrine/orchestration/dagster.py +103 -0
  73. terrine/py.typed +0 -0
  74. terrine/recipes.py +295 -0
  75. terrine/runtime/__init__.py +70 -0
  76. terrine/runtime/api.py +803 -0
  77. terrine/runtime/arrow.py +98 -0
  78. terrine/runtime/backends/base.py +70 -0
  79. terrine/runtime/backends/duckdb.py +645 -0
  80. terrine/runtime/changes.py +71 -0
  81. terrine/runtime/cli.py +108 -0
  82. terrine/runtime/control.py +355 -0
  83. terrine/runtime/cost.py +211 -0
  84. terrine/runtime/events.py +194 -0
  85. terrine/runtime/execute.py +932 -0
  86. terrine/runtime/gc.py +43 -0
  87. terrine/runtime/graph.py +200 -0
  88. terrine/runtime/layers.py +61 -0
  89. terrine/runtime/leases.py +165 -0
  90. terrine/runtime/materialize.py +53 -0
  91. terrine/runtime/owner.py +57 -0
  92. terrine/runtime/planner.py +441 -0
  93. terrine/runtime/planning.py +394 -0
  94. terrine/runtime/saved_plan.py +337 -0
  95. terrine/runtime/snapshot.py +541 -0
  96. terrine/runtime/state.py +585 -0
  97. terrine/runtime/status.py +360 -0
  98. terrine/runtime/synchronization.py +15 -0
  99. terrine/semantic/__init__.py +3 -0
  100. terrine/semantic/bind.py +309 -0
  101. terrine/semantic/io.py +116 -0
  102. terrine/semantic/models.py +342 -0
  103. terrine/semantic/rules.py +113 -0
  104. terrine/semantic/sql.py +185 -0
  105. terrine/semantic/time.py +42 -0
  106. terrine/simulate/__init__.py +24 -0
  107. terrine/simulate/baseline.yaml +57 -0
  108. terrine/simulate/generate.py +182 -0
  109. terrine/simulate/scale.py +234 -0
  110. terrine/simulate/world.py +75 -0
  111. terrine/spec/__init__.py +96 -0
  112. terrine/spec/anchors.py +107 -0
  113. terrine/spec/dataset.py +260 -0
  114. terrine/spec/design.py +361 -0
  115. terrine/spec/expressions.py +440 -0
  116. terrine/spec/io.py +829 -0
  117. terrine/spec/panels.py +359 -0
  118. terrine/spec/sequence.py +165 -0
  119. terrine/spec/state_panel.py +246 -0
  120. terrine/spec/trajectory.py +144 -0
  121. terrine/spec/transforms.py +260 -0
  122. terrine/spec/validate.py +758 -0
  123. terrine/temporal/__init__.py +3 -0
  124. terrine/temporal/aggregate.py +688 -0
  125. terrine/temporal/attributes.py +389 -0
  126. terrine/temporal/daily.py +481 -0
  127. terrine/temporal/first.py +239 -0
  128. terrine/temporal/lookup.py +194 -0
  129. terrine/temporal/nonadditive.py +466 -0
  130. terrine/temporal/prefix.py +104 -0
  131. terrine/temporal/ranges.py +122 -0
  132. terrine/temporal/readiness.py +41 -0
  133. terrine/temporal/retention.py +225 -0
  134. terrine/temporal/sequence.py +900 -0
  135. terrine/temporal/sessionize.py +135 -0
  136. terrine/temporal/sketches.py +329 -0
  137. terrine/windows.py +54 -0
  138. terrine-0.1.0.dev0.dist-info/METADATA +164 -0
  139. terrine-0.1.0.dev0.dist-info/RECORD +144 -0
  140. terrine-0.1.0.dev0.dist-info/WHEEL +4 -0
  141. terrine-0.1.0.dev0.dist-info/entry_points.txt +2 -0
  142. terrine-0.1.0.dev0.dist-info/licenses/LICENSE +202 -0
  143. terrine-0.1.0.dev0.dist-info/licenses/NOTICE +4 -0
  144. terrine-0.1.0.dev0.dist-info/licenses/THIRD_PARTY_NOTICES.txt +219 -0
@@ -0,0 +1,285 @@
1
+ """Strict, data-only version-one dataset tool envelopes."""
2
+
3
+ from collections.abc import Mapping
4
+ from typing import Annotated, Any, Literal, Self
5
+
6
+ from pydantic import (
7
+ BaseModel,
8
+ ConfigDict,
9
+ Field,
10
+ JsonValue,
11
+ field_serializer,
12
+ field_validator,
13
+ model_validator,
14
+ )
15
+
16
+ from terrine.errors import TerrineError, freeze, thaw
17
+
18
+ __all__ = [
19
+ "DesignRequest",
20
+ "Response",
21
+ "ValidationOutput",
22
+ "DesignOutput",
23
+ "PlanReceipt",
24
+ "AgentDatasetReference",
25
+ ]
26
+
27
+
28
+ class Record(BaseModel):
29
+ model_config = ConfigDict(
30
+ extra="forbid", frozen=True, strict=True, validate_default=True, serialize_by_alias=True
31
+ )
32
+ schema_version: Literal[1] = 1
33
+
34
+
35
+ class DesignRequest(Record):
36
+ serialized: str
37
+ base: str | None = None
38
+
39
+
40
+ class NamedDesignRequest(DesignRequest):
41
+ name: str
42
+
43
+
44
+ class PlanReceipt(Record):
45
+ receipt_id: str
46
+ design_hash: str
47
+ plan_hash: str
48
+
49
+
50
+ class DatasetColumn(Record):
51
+ name: str
52
+ data_type: str
53
+ role: str
54
+ complete_column: str | None = None
55
+ reason_column: str | None = None
56
+
57
+
58
+ class AgentDatasetReference(Record):
59
+ dataset: str
60
+ generation: str
61
+ definition_hash: str
62
+ definition_reference: str
63
+ model_hash: str
64
+ manifest_hash: str
65
+ row_count: Annotated[int, Field(ge=0)]
66
+ columns: tuple[DatasetColumn, ...] = ()
67
+
68
+
69
+ class BudgetRequest(Record):
70
+ max_rows: Annotated[int, Field(ge=0)] | None = None
71
+ max_output_bytes: Annotated[int, Field(ge=0)] | None = None
72
+ max_scan_bytes: Annotated[int, Field(ge=0)] | None = None
73
+ strict_scan: bool = True
74
+
75
+
76
+ class DestinationRequest(Record):
77
+ database: str
78
+ schema_name: str = Field(alias="schema")
79
+ dataset: str
80
+
81
+
82
+ class PreviewRequest(Record):
83
+ serialized: str
84
+ budget: BudgetRequest | None = None
85
+ bounded_count: Annotated[int, Field(ge=0)] = 0
86
+
87
+
88
+ class PrepareRequest(Record):
89
+ serialized: str
90
+ destination: DestinationRequest
91
+ invocation_id: str
92
+ budget: BudgetRequest | None = None
93
+
94
+
95
+ class ExecuteRequest(Record):
96
+ receipt_id: str
97
+ request_key: Annotated[str, Field(min_length=1, max_length=256)]
98
+
99
+
100
+ class RunRequest(Record):
101
+ run_id: str
102
+
103
+
104
+ class RunEventsRequest(RunRequest):
105
+ after: str | None = None
106
+ limit: Annotated[int, Field(gt=0)] = 100
107
+
108
+
109
+ class RowPreviewRequest(Record):
110
+ reference: AgentDatasetReference
111
+ limit: Annotated[int, Field(gt=0)]
112
+ columns: tuple[str, ...]
113
+
114
+
115
+ class ValidationOutput(Record):
116
+ spec_hash: str
117
+ required_sources: tuple[str, ...]
118
+ runtime_obligations: tuple[str, ...]
119
+
120
+
121
+ class DesignOutput(ValidationOutput):
122
+ serialized: str
123
+ changed_paths: tuple[str, ...] = ()
124
+
125
+
126
+ class SourceMetadata(Record):
127
+ name: str
128
+ entities: tuple[str, ...]
129
+ facts: tuple[str, ...]
130
+ properties: tuple[str, ...]
131
+
132
+
133
+ class MetricMetadata(Record):
134
+ name: str
135
+ entity: str
136
+ kind: str
137
+ sources: tuple[str, ...]
138
+
139
+
140
+ class PropertyMetadata(Record):
141
+ name: str
142
+ source: str
143
+ dtype: str
144
+ as_of: str
145
+
146
+
147
+ class CatalogOutput(Record):
148
+ sources: tuple[SourceMetadata, ...]
149
+ metrics: tuple[MetricMetadata, ...]
150
+ properties: tuple[PropertyMetadata, ...]
151
+ units: tuple[str, ...]
152
+
153
+
154
+ class CapabilityOutput(Record):
155
+ operations: tuple[str, ...]
156
+ runtime_shapes: tuple[str, ...]
157
+
158
+
159
+ class SchemaOutput(Record):
160
+ document: Mapping[str, JsonValue]
161
+
162
+ @field_validator("document", mode="after")
163
+ @classmethod
164
+ def _freeze_document(cls, value: Mapping[str, Any]) -> Mapping[str, Any]:
165
+ return freeze(value)
166
+
167
+ @field_serializer("document")
168
+ def _serialize_document(self, value: Mapping[str, Any]) -> dict[str, Any]:
169
+ return thaw(value)
170
+
171
+
172
+ class Response[T](Record):
173
+ status: Literal["ok", "refused", "pending"]
174
+ code: str | None = None
175
+ context: Mapping[str, JsonValue] = {}
176
+ suggested_route: str | None = None
177
+ output_reference: PlanReceipt | AgentDatasetReference | None = None
178
+ output: T | None = None
179
+
180
+ @field_validator("context", mode="after")
181
+ @classmethod
182
+ def _freeze_context(cls, value: Mapping[str, Any]) -> Mapping[str, Any]:
183
+ return freeze(value)
184
+
185
+ @field_serializer("context")
186
+ def _serialize_context(self, value: Mapping[str, Any]) -> dict[str, Any]:
187
+ return thaw(value)
188
+
189
+ @model_validator(mode="after")
190
+ def _status_contract(self) -> Self:
191
+ if (self.status == "refused") != (self.code is not None):
192
+ raise ValueError("only refused responses carry refusal codes")
193
+ if self.status == "refused" and (
194
+ self.output is not None or self.output_reference is not None
195
+ ):
196
+ raise ValueError("refusals cannot carry successful outputs")
197
+ return self
198
+
199
+
200
+ _CONTEXT_FIELDS = frozenset({"operation", "kind", "name", "role", "gap", "shape", "limit", "route"})
201
+ _ROUTES = {
202
+ "terrine.design.missing_reference": "Choose a name from inspect_catalog.",
203
+ "terrine.design.invalid_window": "Choose a window with start before end.",
204
+ "terrine.design.gap_violation": (
205
+ "Keep feature windows before the gap and outcome windows after it."
206
+ ),
207
+ "terrine.budget.scan_unknown": (
208
+ "Use an owner-approved backend with a verified scan bound, "
209
+ "or ask the owner to change strict scan policy."
210
+ ),
211
+ "terrine.agent.request_limit": (
212
+ "Ask the owner to create a new tool session with an approved request budget."
213
+ ),
214
+ }
215
+
216
+
217
+ def refusal_response(error: TerrineError) -> Response[Any]:
218
+ """Project stable refusal fields without backend messages or arbitrary context."""
219
+ context = {key: value for key, value in error.context.items() if key in _CONTEXT_FIELDS}
220
+ route = context.get("route")
221
+ return Response(
222
+ status="refused",
223
+ code=error.code,
224
+ context=thaw(context),
225
+ suggested_route=route
226
+ if isinstance(route, str)
227
+ else _ROUTES.get(
228
+ error.code, "Review the typed request and owner-approved dataset configuration."
229
+ ),
230
+ )
231
+
232
+
233
+ class RunOutput(Record):
234
+ run_id: str
235
+ durable_state: str
236
+ phase: str | None = None
237
+ error_code: str | None = None
238
+ pinned_result_ref: str | None = None
239
+ latest_event_cursor: str | None = None
240
+
241
+
242
+ class CancelOutput(Record):
243
+ run_id: str
244
+ disposition: str
245
+ durable_state: str
246
+
247
+
248
+ class EventOutput(Record):
249
+ sequence: int
250
+ kind: str
251
+ state: str | None = None
252
+ phase: str | None = None
253
+
254
+
255
+ class EventsOutput(Record):
256
+ events: tuple[EventOutput, ...]
257
+ next_cursor: str | None
258
+ has_more: bool
259
+ cursor_gap: bool
260
+
261
+
262
+ class DefinitionOutput(DesignOutput):
263
+ definition_digest: str
264
+
265
+
266
+ class RowsOutput(Record):
267
+ columns: tuple[str, ...]
268
+ rows: tuple[tuple[Any, ...], ...]
269
+
270
+ @field_validator("rows", mode="after")
271
+ @classmethod
272
+ def _rows(cls, value):
273
+ return freeze(value)
274
+
275
+ @field_serializer("rows")
276
+ def _serialize_rows(self, value):
277
+ return thaw(value)
278
+
279
+
280
+ class AgentExportManifest(Record):
281
+ dataset: str
282
+ generation: str
283
+ row_count: Annotated[int, Field(ge=0)]
284
+ byte_count: Annotated[int, Field(ge=0)]
285
+ shard_count: Annotated[int, Field(ge=0)]