jano 0.3.1

Temporal partitioning and backtesting utilities for time-correlated datasets.

Jano

Jano is a Python library for defining temporal partitions and backtesting schemes over time-correlated datasets.

The missing layer between ML models and production temporal validation.

Documentation: marmurar.github.io/jano

It is designed for cases where a plain train_test_split() is not enough: transactional data, production simulations, repeated retraining, walk-forward validation, model monitoring, rule evaluation, or any experiment where the ordering of time matters.

The core accepts pandas.DataFrame, numpy.ndarray and polars.DataFrame inputs. pandas remains the internal execution engine, while NumPy and Polars inputs are normalized at the boundary so the split/reporting API stays consistent.

The project is named after Janus, the Roman god of beginnings, transitions and thresholds. That framing fits the library well: Jano helps define how a dataset moves from training periods into evaluation periods, fold after fold.

MCP server

Jano also ships an optional local MCP server so AI agents can use the library through a small, explicit tool surface instead of generating Python ad hoc.

Current MCP tools:

• preview_local_dataset
• plan_walk_forward_simulation
• run_walk_forward_simulation

Install it in a Python 3.10+ environment:

python -m pip install "jano[mcp]"

Run it locally over stdio:

jano-mcp

Or use the module entrypoint:

python -m jano.mcp_server

Example MCP client configuration:

{
  "mcpServers": {
    "jano": {
      "command": "jano-mcp"
    }
  }
}

The MCP layer is intentionally opinionated: it exposes planning and walk-forward simulation first, while the full Python library remains available when you need custom composition.

This is meant for MCP-aware coding assistants such as Claude Code, Claude Desktop, Cursor, Codex runtimes with MCP support, and other local agent environments. The server runs locally and reads only the file paths you provide to its tools; Jano does not upload datasets anywhere by itself.

Why Jano exists

Many machine learning datasets are not just tabular; they are structured over time and often across multiple entities such as users, routes, sellers or products. In those settings, a more faithful view of the data is not "a bag of independent rows" but a temporally ordered process.

Standard evaluation tooling usually assumes observations are i.i.d. enough that a static split is acceptable. That assumption breaks quickly when time matters: future information leaks into training, performance estimates become optimistic, and offline validation stops reflecting what really happens in production.

Most train/test utilities answer a simple question:

"How do I split this dataset once?"

Jano is meant to answer a richer one:

"How would this system have behaved over time if I had trained, retrained and evaluated it under a specific temporal policy?"

That difference is the core of the project. Jano treats evaluation as a temporal simulation rather than a static partition. Instead of defining one split, it defines a policy over time: train window, evaluation horizon, shift between iterations and optional leakage-control gaps. Running that policy produces a sequence of causally valid folds rather than one aggregate estimate.

That also makes it a useful way to evidence drift in simulation results, because temporal shifts in behavior, performance or calibration become visible fold after fold.

That makes it useful not only for machine learning, but for any workflow where the data is time-dependent:

• Backtesting predictive models on transactional data.
• Simulating daily or weekly retraining in production.
• Comparing rolling versus expanding windows.
• Introducing explicit gaps between training and evaluation periods.
• Defining train/test or train/validation/test partitions with durations, row counts or percentages.
• Surfacing drift in simulation outcomes by making temporal changes explicit across folds.

Project direction

Jano is being reshaped as a small, explicit temporal partitioning toolkit with an interface inspired by sklearn.model_selection.

The design goals are:

• Clear, composable temporal partition definitions.
• Low hidden state and predictable behavior.
• Compatibility with pandas-first workflows.
• A splitter-style API that can evolve toward stronger scikit-learn interoperability.
• Rich split objects for inspection, auditability and simulation.

Current API

The recommended high-level surface is intentionally small:

• WalkForwardPolicy for production-like walk-forward evaluation,
• TrainHistoryPolicy for fixed-test, growing-train questions,
• DriftMonitoringPolicy for fixed-train, moving-test questions.

Those classes sit on top of the lower-level building blocks that remain available:

• TemporalSimulation for explicit simulation objects,
• TemporalBacktestSplitter for manual fold iteration,
• TrainGrowthPolicy and PerformanceDecayPolicy for lower-level temporal hypothesis primitives.

The workflow is intentionally compositional:

• start simple with predefined layouts and strategies,
• move to plan() when you want to inspect or filter iterations before running them,
• use the small policy surface when the question is already encapsulated,
• and fall back to manual fold iteration when you want to compose everything yourself: partitions, gaps, feature history and model training logic.

The workflow is intentionally compositional:

• start simple with predefined layouts and strategies,
• move to plan() when you want to inspect or filter iterations before running them,
• use higher-level policies such as TrainGrowthPolicy or PerformanceDecayPolicy when the question is already encapsulated,
• and fall back to manual fold iteration when you want to compose everything yourself: partitions, gaps, feature history and model training logic.

It supports:

• single, rolling and expanding strategies.
• train_test and train_val_test layouts.
• Segment sizes defined as durations like "30D", row counts like 5000, or fractions like 0.7.
• Calendar-aligned duration windows with calendar_frequency="D" when you want complete days instead of elapsed-time windows anchored at the first timestamp.
• Optional gaps before validation or test segments.
• Plain index output through split().
• Rich fold objects through iter_splits().
• Simulation summaries, HTML timeline reports and plot-ready chart data through describe_simulation().
• An adaptive partition engine that keeps pandas, NumPy and Polars inputs native for planning when it is safe, and falls back to pandas when stability is more important.

Example: run a full simulation without manual iteration

import pandas as pd

from jano import TemporalPartitionSpec, WalkForwardPolicy

frame = pd.DataFrame(
    {
        "timestamp": pd.date_range("2024-01-01", periods=60, freq="D"),
        "feature": range(60),
        "target": range(100, 160),
    }
)

policy = WalkForwardPolicy(
    time_col="timestamp",
    partition=TemporalPartitionSpec(
        layout="train_test",
        train_size="30D",
        test_size="1D",
    ),
    step="1D",
    strategy="rolling",
)

result = policy.run(frame, title="One month in production")

print(result.total_folds)
print(result.engine_metadata.to_dict())
print(result.summary.to_frame().head())
print(result.chart_data.segment_stats)

By default, engine="auto" lets Jano choose the safest fast path for partitioning: pandas inputs stay pandas, Polars inputs use Polars column extraction, and NumPy arrays use array indexing. You can force a path with engine="pandas", engine="polars" or engine="numpy" when you need deterministic behavior for a pipeline.

If you want to inspect the full simulation geometry before materializing folds, plan it first:

plan = policy.plan(frame, title="One month in production")
print(plan.total_folds)
print(plan.to_frame().head())

filtered = plan.exclude_windows(
    train=[("2025-12-20", "2026-01-05")],
).select_from_iteration(5)

result = filtered.materialize()

That plan frame includes the explicit iteration index, segment boundaries and row counts for each fold.

You can also anchor a simulation to a specific date and limit how many folds are materialized:

policy = WalkForwardPolicy(
    time_col="timestamp",
    partition=TemporalPartitionSpec(
        layout="train_test",
        train_size="15D",
        test_size="4D",
    ),
    step="1D",
    strategy="rolling",
    start_at="2025-09-01",
    max_folds=15,
)

result = policy.run(frame, title="15 daily retraining iterations")

The recommended walk-forward surface also supports end_at when you want to constrain the simulation to a bounded time window before folds are generated.

When a single timestamp is not enough, WalkForwardPolicy, TemporalSimulation and TemporalBacktestSplitter can also receive a TemporalSemanticsSpec. That lets you keep one column as the reported timeline while using different timestamp columns to decide whether train, validation or test rows are actually eligible. This is useful for production-style leakage control, for example when a target only becomes available at arrived_at even if the operational timeline is anchored on departured_at.

For numpy.ndarray inputs, use integer column references:

import numpy as np

values = np.array(
    [
        ["2025-09-01", 1.2, 10],
        ["2025-09-02", 1.5, 11],
        ["2025-09-03", 1.1, 12],
    ],
    dtype=object,
)

splitter = TemporalBacktestSplitter(
    time_col=0,
    partition=TemporalPartitionSpec(
        layout="train_test",
        train_size="2D",
        test_size="1D",
    ),
    step="1D",
    strategy="single",
)

Example: manual control with the low-level splitter

from jano import TemporalBacktestSplitter, TemporalPartitionSpec

splitter = TemporalBacktestSplitter(
    time_col="timestamp",
    partition=TemporalPartitionSpec(
        layout="train_val_test",
        train_size=0.6,
        validation_size=0.2,
        test_size=0.2,
    ),
    step=0.2,
    strategy="single",
)

for split in splitter.iter_splits(frame):
    print(split.summary())

Example: keep the same test window and grow train backward

This is a special use case. It is useful when you want to study whether more training history really improves the same test slice.

from jano import TrainHistoryPolicy

policy = TrainHistoryPolicy(
    "timestamp",
    cutoff="2025-09-15",
    train_sizes=["7D", "14D", "21D", "28D"],
    test_size="4D",
)

result = policy.evaluate(
    frame,
    model=model,
    target_col="target",
    feature_cols=["feature_1", "feature_2"],
    metrics=["mae", "rmse"],
)

print(result.to_frame()[["train_size", "rmse"]])
print(result.find_optimal_train_size(metric="rmse", tolerance=0.01))

That pattern keeps test fixed while train expands toward the past. It is a practical way to study data efficiency or to estimate how much history is actually needed.

The opposite special case is also common: keep train fixed and move test forward day by day to estimate how long a model or rule keeps its performance without retraining. The two patterns answer different questions:

• fixed test + growing train: how much history do I actually need?
• fixed train + moving test: for how long does performance hold after deployment?

Example of the second pattern:

from jano import DriftMonitoringPolicy

policy = DriftMonitoringPolicy(
    "timestamp",
    cutoff="2025-09-15",
    train_size="30D",
    test_size="3D",
    step="1D",
    max_windows=10,
)

result = policy.evaluate(
    frame,
    model=model,
    target_col="target",
    feature_cols=["feature_1", "feature_2"],
    metrics=["mae", "rmse"],
)

print(result.to_frame()[["window", "test_start", "rmse"]])
print(result.find_drift_onset(metric="rmse", threshold=0.15, baseline="first"))

Example: optimize training history inside each walk-forward iteration

This is the next-level composed question: if each outer test window is allowed to choose its own optimal training history, how much history is needed on average?

from jano import RollingTrainHistoryPolicy, TemporalPartitionSpec

policy = RollingTrainHistoryPolicy(
    "timestamp",
    partition=TemporalPartitionSpec(
        layout="train_test",
        train_size="30D",
        test_size="1D",
    ),
    step="1D",
    strategy="rolling",
    max_folds=10,
    train_sizes=["5D", "10D", "15D", "30D"],
)

result = policy.evaluate(
    frame,
    model=model,
    target_col="target",
    feature_cols=["feature_1", "feature_2"],
    metrics="rmse",
    metric="rmse",
    tolerance=0.01,
)

print(result.to_frame().head())
print(result.summary())

Example: different feature groups can require different history depths

The supervised fold can stay fixed while feature engineering still asks for different lookback windows per feature group.

from jano import FeatureLookbackSpec

split = next(splitter.iter_splits(frame))
lookbacks = FeatureLookbackSpec(
    default_lookback="15D",
    group_lookbacks={"lag_features": "65D"},
    feature_groups={"lag_features": ["lag_30", "lag_60"]},
)

history = split.slice_feature_history(
    frame,
    lookbacks,
    time_col="timestamp",
    segment_name="train",
)

recent_context = history["__default__"]
lag_context = history["lag_features"]

This is useful when recent features only need a short window while lagged or seasonal features need much deeper historical context for the same model.

Example: describe a simulation as HTML

summary = splitter.describe_simulation(frame, title="Walk-forward simulation")
html = splitter.describe_simulation(frame, output="html")
chart_data = splitter.describe_simulation(frame, output="chart_data")

print(summary.total_folds)
print(summary.to_frame().head())
print(chart_data.segment_stats)

That gives you three ways to consume the same simulation:

• summary for tabular metadata and export helpers,
• html for a standalone visual report,
• chart_data for direct Python plotting without reparsing HTML.

The generated report shows each fold across the dataset timeline, with richer summary cards, clearer segment labels and row counts per partition.

Installation

After the first PyPI release, install the package with:

python -m pip install jano

To use Polars inputs directly:

python -m pip install "jano[polars]"

For local development:

python -m pip install -e ".[dev]"
python -m pytest --cov=jano --cov-report=term-missing
python -m sphinx -b html docs docs/_build/html

Jano also exposes its runtime version through jano.__version__.

Release flow

The repository includes a dedicated GitHub Actions workflow for PyPI publication through trusted publishing.

The release path is:

1. Update jano/_version.py.
2. Run python -m pytest -q.
3. Run python -m build and python -m twine check dist/*.
4. Push a tag like v0.3.0.

That tag triggers the Publish workflow, which builds the wheel and source distribution and publishes them to PyPI.

In parallel, the repository also includes a GitHub Release workflow that can create a GitHub Release and attach the built wheel and source distribution for any v* tag. That gives the project a distribution channel even while PyPI access is still being recovered.

Continuous integration and coverage

The repository includes:

• GitHub Actions for tests across multiple Python versions.
• GitHub Pages publication for Sphinx documentation.
• Coverage reporting with pytest-cov.
• Codecov upload and status tracking.

Status

Jano is currently in an early redesign phase. The public API is stabilizing around temporal partition specs, reusable splitters and rich split objects.

That means the project is already usable for experimentation, but it is still a good moment to refine naming, ergonomics and compatibility guarantees before publishing broadly.

Authors

• Marcos Manuel Muraro

Contributing

Feedback and design discussion are especially valuable right now. If you are using temporal backtesting for ML, analytics, operations or experimentation, that context can help shape the API in the right direction.

Star history