Metadata-Version: 2.4
Name: jano
Version: 0.3.1
Summary: Temporal partitioning and backtesting utilities for time-correlated datasets.
Author-email: Marcos Manuel Muraro <mmmuraro@gmail.com>
Maintainer-email: Marcos Manuel Muraro <mmmuraro@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/marmurar/jano
Project-URL: Documentation, https://marmurar.github.io/jano/
Project-URL: Repository, https://github.com/marmurar/jano
Project-URL: Issues, https://github.com/marmurar/jano/issues
Project-URL: Changelog, https://github.com/marmurar/jano/releases
Keywords: backtesting,time-series,walk-forward-validation,model-selection,temporal-validation,pandas,time-series-validation,simulation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: pandas>=2.0
Requires-Dist: numpy>=1.24
Provides-Extra: mcp
Requires-Dist: mcp[cli]<2,>=1.0; python_version >= "3.10" and extra == "mcp"
Provides-Extra: polars
Requires-Dist: polars>=1.0; extra == "polars"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: mcp[cli]<2,>=1.0; python_version >= "3.10" and extra == "dev"
Requires-Dist: polars>=1.0; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: sphinx>=7.4; extra == "dev"
Requires-Dist: twine>=5.1; extra == "dev"
Dynamic: license-file

# Jano

<p align="center">
  <img src="https://raw.githubusercontent.com/marmurar/jano/master/imgs/jano_logo.png" alt="Jano logo" width="260" />
</p>

[![CI](https://github.com/marmurar/jano/actions/workflows/ci.yml/badge.svg)](https://github.com/marmurar/jano/actions/workflows/ci.yml)
[![Docs](https://github.com/marmurar/jano/actions/workflows/docs.yml/badge.svg)](https://github.com/marmurar/jano/actions/workflows/docs.yml)
[![codecov](https://codecov.io/gh/marmurar/jano/graph/badge.svg)](https://codecov.io/gh/marmurar/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](https://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:

```bash
python -m pip install "jano[mcp]"
```

Run it locally over stdio:

```bash
jano-mcp
```

Or use the module entrypoint:

```bash
python -m jano.mcp_server
```

Example MCP client configuration:

```json
{
  "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

```python
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:

```python
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:

```python
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:

```python
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

```python
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.

```python
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:

```python
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?

```python
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.

```python
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

```python
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:

```bash
python -m pip install jano
```

To use Polars inputs directly:

```bash
python -m pip install "jano[polars]"
```

For local development:

```bash
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

[![Star History Chart](https://api.star-history.com/svg?repos=marmurar/jano&type=Date)](https://star-history.com/#marmurar/jano&Date)
