sci_task_io 0.0.1

# sci_task_io

`sci_task_io` is a cross-language library for reading, writing, validating, and organizing scientific trajectory data.

The repository defines one canonical JSON trajectory contract and provides:
- a Python runtime for trajectory IO, aggregation, processed NPY output, and model discovery
- a Rust runtime for trajectory IO, validation, checkpoint handling, and directory-backed trajectory series loading

## Repository Layout

- `schema/`
  - [`schema.md`](/home/acht/Desktop/Projects/SciTaskIO/schema/schema.md): human-readable schema
  - [`trajectory.json.schema`](/home/acht/Desktop/Projects/SciTaskIO/schema/trajectory.json.schema): machine-readable JSON schema
  - [`signal_label.npy.schema.md`](/home/acht/Desktop/Projects/SciTaskIO/schema/signal_label.npy.schema.md): processed NPY payload shape
  - `fixtures/contract/`: valid and invalid JSON fixtures
- `python/`
  - `src/sci_task_io/trajectory/`: trajectory API
  - `src/sci_task_io/model/`: model and model-cluster utilities
  - `examples/`: runnable examples
- `rust/`
  - `src/trajectory/`: Rust trajectory modules
  - `examples/`: runnable examples

## Trajectory Contract

Canonical JSON files are stored as `<series_id>.json`.

Top-level shape:
- `metadata`: optional object
- `scalars`: optional scalar key-value object
- `signals`: required object keyed as `track_1`, `track_2`, ...

Each track contains:
- `label`: non-empty string
- `times`: array of time values
- `signal`: array aligned 1:1 with `times`

Python can also write processed per-label outputs as `<signal_label>.npy`.

## Python API

Top-level imports from `sci_task_io`:
- `Trajectory`
- `SignalTrack`
- `TrajectorySeries`
- `Model`
- `ModelCluster`
- `load_trajectory_json`
- `save_trajectory_json`
- `trajectory_from_payload`
- `validate_trajectory_payload`

Typical usage:

```python
from sci_task_io import Trajectory, TrajectorySeries, SignalTrack

trajectory = Trajectory.from_json("run_A.json")
trajectory.save_json("copy.json")

series = TrajectorySeries.from_dir("runs")
written = series.process("processed")

track = SignalTrack.from_npy("frequencies.npy")
```

## Rust API

Main module:
- `sci_task_io::trajectory`

Important exports:
- `Trajectory`
- `SignalTrack`
- `TrajectorySeries`
- `TrajectoryBuilder`
- `load_trajectory_json`
- `save_trajectory_json`
- `trajectory_from_payload`
- `validate_trajectory_payload`
- checkpoint helpers such as `load_latest_checkpoint` and `sync_checkpoint_dirs`

Typical usage:

```rust
use sci_task_io::trajectory::{Trajectory, TrajectorySeries};

let trajectory = Trajectory::from_json(path, false)?;
trajectory.save_json(out_path)?;

let mut series = TrajectorySeries::from_dir(dir, false)?;
let ids = series.serial_ids()?;
```

## Examples

- Python: [`python/examples/basic_usage.py`](/home/acht/Desktop/Projects/SciTaskIO/python/examples/basic_usage.py)
- Rust: [`rust/examples/basic_usage.rs`](/home/acht/Desktop/Projects/SciTaskIO/rust/examples/basic_usage.rs)
- Rust: [`rust/examples/series_usage.rs`](/home/acht/Desktop/Projects/SciTaskIO/rust/examples/series_usage.rs)

## Scope

- Python includes model discovery and processed NPY helpers.
- Rust currently does not implement model discovery or NPY processing.