terrine

Terrine turns event tables and an explicit unit roster into analytical and ML datasets with point-in-time features and future outcomes. You declare what each row means, its time zero and source completeness; Terrine compiles the dataset and preserves the difference between observed zero and unknown.

The example below produces these value columns (anchor_id and t0 omitted here):

Install

Requires CPython 3.13 or 3.14. Install the DuckDB backend and pandas for this example:

uv pip install 'terrine[duckdb,pandas]'

Use terrine[duckdb] for Arrow-only workflows, or add the polars extra for Polars.

Build a study dataset

Run this locally: the temporary DuckDB database contains two users, including b with no events. Nothing is uploaded.

from tempfile import TemporaryDirectory
import ibis
import terrine as tr

with TemporaryDirectory(prefix="terrine-first-") as directory:
    con = ibis.duckdb.connect(f"{directory}/analytics.duckdb")
    try:
        con.raw_sql("CREATE TABLE users AS SELECT * FROM (VALUES ('a'), ('b')) t(user_id)")
        con.raw_sql("CREATE TABLE events AS SELECT 'a' AS user_id, unnest([TIMESTAMP '2025-01-01 12:00:00', TIMESTAMP '2025-01-02 00:00:00', TIMESTAMP '2025-01-02 12:00:00']) AS occurred_at")
        model = tr.Model.from_tables(
            con, units={"user": tr.UnitSource("users", "user_id")},
            events={"sessions": tr.Events("events", "occurred_at", {"user": "user_id"}, complete=("2025-01-01", "2025-01-03"))},
        )
        design = tr.recipes.time_series(
            "user", every="1d", start="2025-01-02", end="2025-01-03",
            features={"before": tr.agg("sessions_count", window=("-1d", "0s"))},
            outcomes={"after": tr.agg("sessions_count", window=("0s", "1d"))},
        )
        data = design.build(model).to_pandas()
        print(data.sort_values("unit").to_string(index=False))
    finally:
        con.disconnect()

Model → Design → Frame → Dataset: bind tables, describe rows, build lazily, then collect or optionally stage a pinned generation. The event at midnight belongs to after, not before. The compact pandas view keeps each value's __complete / __reason columns; Arrow retains all observation metadata. See your first dataset for budgets, refusals and staging.

Datasets you can build

Each tr.recipes constructor returns an ordinary, editable Design; the low-level API remains available.

Common feature patterns: rolling windows, active-before eligibility, attributes at t0, recency and true/false labels.

Five rules

1. Choose t0. Every row has an explicit time zero: fixed, scheduled or event-based.
2. Use half-open windows. [start, end) includes the start, excludes the end; offsets are elapsed durations, not calendar dates.
3. Features before, outcomes after. Features and eligibility cannot look beyond the pre-t0 cutoff; outcomes describe follow-up.
4. Declare completeness. Model.from_tables requires complete= on every Events descriptor; with Model.from_catalog, only sources selected by the Design need Coverage. Both declare complete local days, never inferred from the latest event.
5. Null is not zero. A complete empty count is zero; unavailable values stay null with __reason. Unknown eligibility refuses export rather than silently dropping a row.

Supported warehouses

See backend compatibility for extras, consistent-read semantics, supported operations, precision and executable warehouse examples.

Guides

• All guides · Capabilities · Inherent limits · Refusal codes
• Training/scoring and saved dataset definitions · Library hand-offs (Terrine makes no causal estimates or identification claims)
• Durable runtime and saved plans · Owned inputs
• Restricted dataset tools · Airflow, Dagster and dbt
• Cost and data residency · Synthetic worlds with independent expected rows

Contributing? See CONTRIBUTING.md for setup, test tiers and the Contributor License Agreement.

License

Apache License 2.0; see NOTICE.