Metadata-Version: 2.4
Name: janus-tachyon-rs
Version: 0.2.1
Requires-Dist: loguru>=0.7.3
Requires-Dist: msgpack>=1.1.2
Requires-Dist: maturin>=1.5,<2.0 ; extra == 'dev'
Requires-Dist: matplotlib>=3.8.0 ; extra == 'dev'
Requires-Dist: networkx>=3.0 ; extra == 'dev'
Requires-Dist: mypy>=1.19.1 ; extra == 'dev'
Requires-Dist: numpy>=1.26.0 ; extra == 'dev'
Requires-Dist: pandas>=2.0.0 ; extra == 'dev'
Requires-Dist: pre-commit>=4.5.1 ; extra == 'dev'
Requires-Dist: ruff>=0.15.7 ; extra == 'dev'
Requires-Dist: sphinx>=7.0.0 ; extra == 'docs'
Requires-Dist: sphinx-rtd-theme>=2.0.0 ; extra == 'docs'
Requires-Dist: myst-parser>=2.0.0 ; extra == 'docs'
Requires-Dist: sphinx-autodoc-typehints>=1.24.0 ; extra == 'docs'
Requires-Dist: linkify-it-py>=2.0.0 ; extra == 'docs'
Requires-Dist: numpy>=1.26.0 ; extra == 'numpy'
Requires-Dist: pandas>=2.0.0 ; extra == 'pandas'
Requires-Dist: pytest>=7.0 ; extra == 'test'
Requires-Dist: pytest-benchmark>=5.2.3 ; extra == 'test'
Requires-Dist: pytest-cov>=5.0.0 ; extra == 'test'
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: numpy
Provides-Extra: pandas
Provides-Extra: test
License-File: LICENSE-APACHE
License-File: LICENSE-MIT
Summary: Extensible, non-linear state travel powered by the Tachyon-RS engine.
Author-email: "Eduardo J. Ruiz" <eduardo.j.ruiz@gmail.com>
License: MIT OR Apache-2.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# Janus 🏺

[![Janus CI](https://github.com/goldenphoenix713/janus/actions/workflows/ci.yml/badge.svg)](https://github.com/goldenphoenix713/janus/actions/workflows/ci.yml)
[![License: MIT/Apache-2.0](https://img.shields.io/badge/License-MIT%2FApache--2.0-blue.svg)](LICENSE-MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/release/python-3110/)

> **The Extensible Multiverse Engine for Python Objects.**

Janus provides a Git-like API for branching, switching, and flattening the state of complex Python objects, powered by a lightning-fast Rust backend (**Tachyon-RS**). No deep-copying, no manual history tracking, and near-zero performance penalties.

## 📦 Installation

```bash
pip install janus-tachyon-rs
```

## 🚀 Getting Started

Janus allows you to opt-in to complexity. Start with a simple linear history or dive into multiversal branching.

### Linear Mode — Undo / Redo

```python
from janus import TimelineBase

class Document(TimelineBase):
    def __init__(self) -> None:
        super().__init__()
        self.text = ""

doc = Document()
doc.text = "Hello"
doc.text = "Hello World"

doc.undo()
print(doc.text)  # "Hello"

doc.redo()
print(doc.text)  # "Hello World"
```

### Multiversal Mode — Branching

```python
from janus import MultiverseBase

class Simulation(MultiverseBase):
    def __init__(self) -> None:
        super().__init__()
        self.points = [1, 2, 3]

sim = Simulation()
sim.branch("stable")

# Perform mutations
sim.points.append(999)
print(sim.points)  # [1, 2, 3, 999]

# Multiversal rollback via Tachyon-RS
sim.jump_to("stable")
print(sim.points)  # [1, 2, 3]
```

## 📊 Visualization

Janus features a built-in visualization suite to inspect the state DAG.

### Basic Visualization (Mermaid)

```python
# Returns a Mermaid.js diagram string
print(sim.visualize())
```

### Pluggable Backends (Matplotlib)

Janus supports multiple backends through the `plot()` API:

```python
# Renders a graphical plot using Matplotlib/NetworkX
fig = sim.plot(backend="matplotlib", title="Multiverse History")
```

**Mermaid Output Example:**

```mermaid
graph LR
    node0("Node 0<br/><b>__genesis__</b>")
    style node0 fill:#e1f5fe,stroke:#01579b
    node1["Node 1"]
    node2("Node 2<br/><b>dev</b>")
    style node2 fill:#e1f5fe,stroke:#01579b
    node3["Node 3"]
    node4(("Node 4<br/><b>main</b>"))
    style node4 fill:#ff9ce6,stroke:#333,stroke-width:4px
    node0 --> node1
    node1 --> node2
    node1 --> node3
    node3 --> node4
    node2 --> node4
```

## 🔀 Container-Aware Merging

Janus supports **intelligent 3-way reconciliation** for native Python lists and dictionaries. Unlike blind-append approaches, Janus **rebases** parallel mutations:

- **List Index Shifting**: If two branches insert items at different indices, Janus automatically shifts indices to preserve intent.
- **Conflict Detection**: Detects and resolves parallel edits to the same dictionary keys or list positions according to configurable strategies (`strict`, `overshadow`, `preserve`).
- **Custom Callbacks**: Provide a custom Python function to resolve conflicts with domain-specific logic (e.g., averaging numeric values).

```python
def average_strategy(name, base, source, target):
    if isinstance(source, (int, float)):
        return (source + target) / 2
    return source  # Default to source for other types

sim.merge("feature", strategy=average_strategy)
```

## 🧹 History Management

To maintain peak performance in long-running simulations, Janus supports **automated history pruning**. You can limit the depth of the state DAG to keep memory and traversal costs constant:

```python
# Keep only the last 1,000 mutations
sim.max_history = 1000

# Or manually trigger a prune
sim.prune()
```

## 🏗️ Architectural Pillars

1. **Extensible Plugin Registry**: Register a `JanusAdapter` to track `pandas.DataFrames`, `numpy.ndarrays`, `torch.Tensors`, or any custom object without slowing down the core engine.
2. **Timeline Extraction**: Flatten complex multiversal paths into linear audit sequences for visualization and debugging.
3. **Third-Party Integration**: Built-in `TrackedDataFrame` and `TrackedNumpyArray` support with full indexer and view-tracking.

## 🚀 Use Cases

- **AI Agent Experiments**: Allow agents to test multiple paths in parallel and revert with knowledge of failed states.
- **Data Science Workflows**: Instantly reverse complex object states without rerunning expensive computation cells.
- **Non-Linear Document History**: Manage "what-if" scenarios for complex file and data structures.

## 📚 Documentation

The full documentation is available at [janustachyon-rs.readthedocs.io](https://janustachyon-rs.readthedocs.io/en/latest/).

- [Getting Started](https://janustachyon-rs.readthedocs.io/en/latest/getting_started.html)
- [API Reference](https://janustachyon-rs.readthedocs.io/en/latest/api/index.html)
- [Architecture Deep Dive](https://janustachyon-rs.readthedocs.io/en/latest/architecture/index.html)
- [Contributing Guide](CONTRIBUTING.md)

## ⚡ Powered by Tachyon-RS

Under the hood, Janus offloads all state delta logic to **Tachyon-RS**, a modularized Rust engine that operates on a Directed Acyclic Graph (DAG) of state nodes. By storing only bi-directional operations and utilizing specialized modules for graph traversal and reconciliation, Tachyon-RS enables time travel with $O(1)$ logging overhead.

## License

Janus is distributed under the terms of both the [MIT license](LICENSE-MIT) and the [Apache License (Version 2.0)](LICENSE-APACHE).

