jano 0.3.1__tar.gz

jano-0.3.1/LICENSE.txt

@@ -0,0 +1,20 @@
+The MIT License (MIT) 
+
+Copyright (c) 2020, Marcos Manuel Muraro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+1. The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

jano-0.3.1/PKG-INFO

@@ -0,0 +1,522 @@
+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)