Documentation

Timefence v0.9.1

Timefence is a temporal correctness layer for ML training data. It guarantees that no future data leaks into your training set by enforcing point-in-time correctness at the moment of dataset construction.

It is not a feature store, data orchestrator, data quality framework, or ML pipeline. Timefence does one thing: ensures feature_time < label_time for every row.

Installation

Timefence requires Python 3.9+ and pip.

pip install timefence

Optional extras:

# Jupyter notebook support
pip install timefence[notebook]

# Development dependencies
pip install timefence[dev]

Dependencies: duckdb>=1.0.0, click>=8.0.0, rich>=13.0.0, pandas>=1.5.0. No Spark, no cloud infrastructure.

Quickstart

Generate a complete example project with synthetic data and planted leakage scenarios:

timefence quickstart churn-example
cd churn-example

This creates a self-contained directory with:

• timefence.yaml — Project configuration
• features.py — 4 feature definitions
• data/ — Synthetic parquet files (users, transactions, labels)
• data/train_LEAKY.parquet — Pre-built dataset with planted leakage
• README.md — Next-step instructions

Now audit the leaky dataset:

timefence audit data/train_LEAKY.parquet

Then build a clean one:

timefence build -o train_CLEAN.parquet

Temporal Correctness

The core invariant Timefence enforces is:

feature_time < label_time - embargo

For every row in your training set, the feature value used must have been available strictly before the label event time (minus any embargo buffer). This prevents future data leakage — the most common and hardest-to-detect source of inflated ML metrics.

In inclusive join mode, the condition relaxes to:

feature_time <= label_time - embargo

Embargo

Real-world ML pipelines have latency: data arrives late, ETL jobs run on schedules, and features take time to compute. The embargo parameter models this lag.

rolling_spend = timefence.Feature(
    source=transactions,
    sql="SELECT ...",
    embargo="1d"  # Feature available 1 day after event
)

With embargo="1d", a feature recorded at 2024-03-15 10:00 is only eligible for labels at 2024-03-16 10:00 or later. This prevents optimistic leakage from features that wouldn't actually be available in production.

Accepted formats: "30d", "1d12h", "6h", "30m", "15s". See Duration Format.

Join Logic

Timefence performs an as-of join (also called a point-in-time join) for each feature. For each label row, it finds the most recent feature value that satisfies the temporal constraint.

Two modes are available:

Additional constraints:

• max_lookback — Maximum age of a feature value (default: "365d"). Features older than this are treated as missing.
• max_staleness — If set, features older than this threshold are treated as missing even if within the lookback window. Must satisfy: max_lookback >= max_staleness > embargo.

Time-Based Splits

Build separate train/validation/test files split by label time:

result = timefence.build(
    labels=labels,
    features=[rolling_spend, user_country],
    output="dataset.parquet",
    splits={
        "train": ("2023-01-01", "2024-01-01"),
        "valid": ("2024-01-01", "2024-07-01"),
        "test":  ("2024-07-01", "2025-01-01"),
    },
)

# result.splits = {"train": Path(...), "valid": Path(...), "test": Path(...)}

Each split file contains only labels whose label_time falls within the given range. All temporal correctness guarantees still apply per-row.

Caching & Store

Timefence can track builds and cache intermediate results using a local Store:

store = timefence.Store(".timefence")

result = timefence.build(
    labels=labels,
    features=[rolling_spend],
    output="train.parquet",
    store=store,
)

Cache keys are computed from content hashes of source files, feature definitions, and build parameters. If nothing has changed, subsequent builds return cached results in milliseconds.

Guide: Audit Existing Data

Already have a training dataset? Audit it for temporal leakage without rebuilding.

Step 1: Inspect your data

timefence inspect data/train.parquet

This shows column types and suggests which columns are likely keys and timestamps.

Step 2: Run the audit

import timefence

transactions = timefence.Source(
    path="data/transactions.parquet",
    keys=["user_id"],
    timestamp="created_at",
)

rolling_spend = timefence.Feature(
    source=transactions,
    columns=["amount"],
    embargo="1d",
)

report = timefence.audit(
    data="data/train.parquet",
    features=[rolling_spend],
    keys=["user_id"],
    label_time="label_time",
)

print(report)
# Per-feature breakdown: clean/leaky row counts, severity, max leakage

Step 3: Inspect results

# Check overall status
report.has_leakage        # True/False
report.leaky_features     # ["rolling_spend_30d"]
report.clean_features     # ["user_country"]

# Per-feature details
detail = report["rolling_spend_30d"]
detail.leaky_row_count    # 1520
detail.leaky_row_pct      # 0.304
detail.severity           # "HIGH"
detail.max_leakage        # timedelta(days=15)

# Export
report.to_html("audit_report.html")
report.to_json("audit_report.json")

Guide: Build from Scratch

Build a point-in-time correct training dataset from raw data.

import timefence

# 1. Define sources
transactions = timefence.Source(
    path="data/transactions.parquet",
    keys=["user_id"],
    timestamp="created_at",
)

users = timefence.Source(
    path="data/users.parquet",
    keys=["user_id"],
    timestamp="updated_at",
)

# 2. Define features
rolling_spend = timefence.Feature(
    source=transactions,
    sql="""
        SELECT user_id, created_at,
        SUM(amount) OVER (
            PARTITION BY user_id
            ORDER BY created_at
            RANGE INTERVAL 30 DAYS PRECEDING
        ) AS spend_30d
        FROM {source}
    """,
    name="rolling_spend_30d",
    embargo="1d",
)

user_country = timefence.Feature(
    source=users,
    columns=["country"],
)

# 3. Define labels
labels = timefence.Labels(
    path="data/labels.parquet",
    keys=["user_id"],
    label_time="label_time",
    target="churned",
)

# 4. Build
result = timefence.build(
    labels=labels,
    features=[rolling_spend, user_country],
    output="train_CLEAN.parquet",
)

print(result)
# rows: 5000, columns: 4, duration: 0.8s

Guide: CI/CD Integration

Add temporal correctness checks to your CI pipeline.

Using the CLI

# Exits with code 1 if leakage is found
timefence audit data/train.parquet --strict

Using Python

report = timefence.audit(
    data="data/train.parquet",
    features=[rolling_spend, user_country],
    keys=["user_id"],
    label_time="label_time",
)

# Raises TimefenceLeakageError if any leakage detected
report.assert_clean()

GitHub Actions example

- name: Audit training data
  run: |
    pip install timefence
    timefence audit data/train.parquet \
      --features features.py \
      --keys user_id \
      --label-time label_time \
      --strict

Python API Reference

timefence.Source(
    path=None,
    *,
    keys,
    timestamp,
    name=None,
    format=None,
    delimiter=",",
    timestamp_format=None,
    df=None,
)

# Explicit format selection
transactions = timefence.ParquetSource("data/tx.parquet", keys="user_id", timestamp="ts")
events = timefence.CSVSource("data/events.csv", keys="user_id", timestamp="ts")

source = timefence.SQLSource(
    query="SELECT * FROM read_parquet('data/*.parquet')",
    keys="user_id",
    timestamp="created_at",
    name="all_transactions",
    connection=None,  # Optional: DuckDB database path
)

timefence.Feature(
    source,
    *,
    columns=None,
    sql=None,
    transform=None,
    name=None,
    embargo=None,
    key_mapping=None,
    on_duplicate="error",
)

# Mode 1: Column selection
country = timefence.Feature(source=users, columns=["country"])

# Mode 2: SQL (inline)
spend = timefence.Feature(
    source=transactions,
    sql="""
        SELECT user_id, created_at,
        SUM(amount) OVER (
            PARTITION BY user_id ORDER BY created_at
            RANGE INTERVAL 30 DAYS PRECEDING
        ) AS spend_30d
        FROM {source}
    """,
    name="rolling_spend_30d",
    embargo="1d",
)

# Mode 2: SQL (file)
spend = timefence.Feature(
    source=transactions,
    sql=Path("features/rolling_spend.sql"),
)

# Mode 3: Python transform
def compute_score(conn, source_table):
    return conn.sql(f"""
        SELECT user_id, created_at AS feature_time,
               raw_score * 2.5 AS adjusted_score
        FROM {source_table}
    """)

score = timefence.Feature(source=transactions, transform=compute_score)

timefence.Labels(
    *,
    path=None,
    df=None,
    keys,
    label_time,
    target,
)

labels = timefence.Labels(
    path="data/labels.parquet",
    keys=["user_id"],
    label_time="label_time",
    target="churned",
)

base_features = timefence.FeatureSet(
    name="churn_features_v1",
    features=[rolling_spend, user_country, login_count],
)

# Use in build/audit like individual features
result = timefence.build(
    labels=labels,
    features=[base_features, new_experimental_feature],
    output="train.parquet",
)

timefence.build(
    labels,
    features,
    output=None,
    *,
    max_lookback="365d",
    max_staleness=None,
    join="strict",
    on_missing="null",
    splits=None,
    store=None,
    flatten_columns=False,
    progress=None,
) -> BuildResult

report = timefence.audit(
    data="data/train.parquet",
    features=[rolling_spend, user_country],
    keys=["user_id"],
    label_time="label_time",
    max_lookback="365d",
    max_staleness=None,
    join="strict",
)

report = timefence.audit.temporal(
    data="data/train.parquet",
    feature_time_columns={
        "spend_30d": "spend_computed_at",
        "country": "country_updated_at",
    },
    label_time="label_time",
)

result = timefence.explain(
    labels=labels,
    features=[rolling_spend, user_country],
    max_lookback="365d",
    max_staleness=None,
    join="strict",
)

print(result)  # Human-readable join plan

result = timefence.diff(
    old="train_v1.parquet",
    new="train_v2.parquet",
    keys=["user_id"],
    label_time="label_time",
    atol=1e-10,  # Absolute tolerance for numeric comparison
    rtol=1e-7,   # Relative tolerance for numeric comparison
)

store = timefence.Store(".timefence")

# Pass to build()
result = timefence.build(labels=labels, features=features, store=store)

# List past builds
builds = store.list_builds()  # Newest first

# Get a specific build
manifest = store.get_build("abc123")

CLI Reference

timefence -v <command>       # Verbose: show generated SQL and build details
timefence --debug <command>  # Debug: full output including DuckDB internals

# Basic audit
timefence audit data/train.parquet

# With explicit options
timefence audit data/train.parquet \
  --features features.py \
  --keys user_id \
  --label-time label_time

# CI mode: exit code 1 if leakage found
timefence audit data/train.parquet --strict

# Export reports
timefence audit data/train.parquet --html report.html
timefence audit data/train.parquet --json

# Basic build
timefence build \
  --labels data/labels.parquet \
  --features features.py \
  -o train.parquet

# With all options
timefence build \
  --labels data/labels.parquet \
  --features features.py \
  -o train.parquet \
  --max-lookback 365d \
  --max-staleness 30d \
  --on-missing null \
  --join-mode strict

# Time-based splits
timefence build \
  --labels data/labels.parquet \
  --features features.py \
  -o train.parquet \
  --split train:2023-01-01:2024-01-01 \
  --split test:2024-01-01:2025-01-01

# Dry run (preview plan without executing)
timefence build \
  --labels data/labels.parquet \
  --features features.py \
  -o train.parquet \
  --dry-run

# Full explain
timefence explain \
  --labels data/labels.parquet \
  --features features.py

# Single feature
timefence explain --features features.py:rolling_spend_30d

# JSON output
timefence explain --features features.py --json

timefence diff train_v1.parquet train_v2.parquet \
  --keys user_id \
  --label-time label_time

# Custom tolerance
timefence diff v1.parquet v2.parquet \
  --keys user_id \
  --label-time label_time \
  --atol 0.01 \
  --rtol 0.001

# JSON output
timefence diff v1.parquet v2.parquet \
  --keys user_id \
  --label-time label_time \
  --json

timefence inspect data/transactions.parquet
timefence inspect data/events.csv --json

# Default churn example
timefence quickstart churn-example

# Minimal version
timefence quickstart myproject --minimal

timefence catalog --features features.py
timefence catalog --features features.py --json

timefence doctor
timefence doctor --json

# Current directory
timefence init

# Specific directory
timefence init my-project/

Configuration (timefence.yaml)

Timefence looks for a timefence.yaml in the current directory. All fields are optional — CLI flags and Python API arguments take precedence.

name: churn-model
version: "1.0"

# Feature file(s)
features:
  - features.py

# Label configuration
labels:
  path: data/labels.parquet
  keys: [user_id]
  label_time: label_time
  target: [churned]

# Default parameters
defaults:
  max_lookback: 365d
  join: strict          # "strict" or "inclusive"
  on_missing: "null"    # "null" or "skip"

# Store directory for build tracking
store: .timefence/

# Output directory (relative paths in build resolve against this)
output:
  dir: artifacts/

Errors

All Timefence errors follow a consistent format: WHAT happened, WHY it happened, WHERE in the data, and HOW TO FIX it.

Duration Format

Timefence accepts human-readable duration strings wherever a time duration is expected (embargo, max_lookback, max_staleness).

You can also pass a Python timedelta object directly in the Python API.