Metadata-Version: 2.4
Name: tomii-rt
Version: 1.2.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Rust
Classifier: Topic :: System :: Distributed Computing
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Requires-Dist: pydantic>=2.0
Requires-Dist: optuna>=3 ; extra == 'agent-tuning'
Requires-Dist: datamodel-code-generator>=0.25 ; extra == 'dev'
Requires-Dist: pytest>=7.0 ; extra == 'dev'
Requires-Dist: mypy>=1.0 ; extra == 'dev'
Requires-Dist: ruff>=0.4 ; extra == 'dev'
Requires-Dist: matplotlib>=3.0 ; extra == 'viz'
Provides-Extra: agent-tuning
Provides-Extra: dev
Provides-Extra: viz
License-File: LICENSE
Summary: Python API for the Τομί task-graph framework
Keywords: task-graph,streaming,mimo,scheduling,low-latency
Author: Τομί Team
License-Expression: Apache-2.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/Giotyp/Tomii/blob/main/CHANGELOG.md
Project-URL: Homepage, https://github.com/Giotyp/Tomii
Project-URL: Repository, https://github.com/Giotyp/Tomii

<div align="center">
  <img alt="Tomii — task-graph runtime for streaming pipelines"
       src="https://tomii.dev/img/logo.svg"
       width="110">
  <h1>Τομί (Tomii)</h1>

[Website] | [Guide] | [Reference]

</div>

[Website]: https://tomii.dev/
[Guide]: https://tomii.dev/docs/guide/getting-started/installation
[Reference]: https://tomii.dev/docs/reference/cli

**Task-graph framework for streaming pipelines, MIMO workloads, and agent-tuneable applications.**

> **NOTE**
> Tomii is a research prototype under active development. Interfaces and
> performance characteristics may change between releases; it is best suited
> for research and experimentation today.

Tomii implements **Tripartite Decoupling** separating the three following artifacts: 1) Computation structure, 2) Kernel Implementation, 3) Runtime. 
Each artifact can be modified independently and Tomii is responsible for combining them at compile (transform kernels into tomii-suitable format) or execution time (parse computation structure description).

Tomii is *not* a general-purpose Taskflow or TBB replacement. For pure single-frame
micro-task DAGs where dispatch overhead dominates, Taskflow is faster. Tomii's advantage
is in workloads that benefit from concurrent frames, generational slot reuse, and
structured graph surfaces — particularly MIMO-class packet-driven pipelines and
agent-driven automated optimisation loops.

Each benchmark under `bench/<name>/` is verifier-gated and reproducible from this
repository — run the script in its directory; see `bench/*/README.md` for the topology,
metric definition, and run instructions. Measured comparison numbers are published in
the project documentation, not in these READMEs.

---

## Python API (recommended)

```python
import tomii as tm

app = tm.Graph()

buf_size    = app.var("buf_size", 100)
fft_planner = app.var("fft_planner", func="fft_planner", args=[buf_size])

gen_vec     = app.node("gen_vec",     func="generate_vector", factor=200, args=[buf_size])
compute_fft = app.node("compute_fft", func="compute_fft",     factor=200,
                       args=[fft_planner, gen_vec.out()])
vec_mat     = app.node("vec_mat",     func="vec_to_mat",      factor=200,
                       args=[gen_vec.out(), compute_fft.wait()])

app.build(func_path="plugin/src/lib.rs", plugin_manifest="plugin/Cargo.toml")
app.run(workers=4, slots=2, timing="timing.csv")
```

### Install

```bash
# From PyPI — the distribution is named `tomii-rt`; the import name is `tomii`.
# 1.2.0 ships wheels for Linux (x86_64, arm64) and macOS (Intel, Apple
# Silicon), CPython 3.9–3.14 including free-threaded 3.13t/3.14t.
# (Windows wheels are planned for a later release.)
pip install tomii-rt          # then:  import tomii

# From source (for development)
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
```

The Rust crates are published on crates.io: `tomii-core`, `tomii-types`,
`tomii-macro`, `tomii-converter` (`cargo add tomii-core`).

### Graph API

| Method | Description |
|---|---|
| `app.var(name, value)` | Constant initialization |
| `app.var(name, func=..., args=[...])` | Computed initialization |
| `app.node(name, func=..., args=[...], factor=...)` | Computation node; `factor` = parallel instances |
| `app.post_node(...)` | Post-computation cleanup node |
| `node.out(i)` | Data dependency on instance `i` (`$res`) |
| `node.wait(i)` | Barrier — wait for instance `i` (`$barrier`) |
| `('dep', node)` | Ordering-only dependency, no output (`$dep`) |
| `app.network(**cfg)` | Configure UDP/TCP packet-driven dispatch |
| `app.to_json()` | Export graph to JSON |

### Type system

```python
tm.i32(-5) / tm.f32(3.14) / tm.String("hello") / tm.bool_(True)
tm.Complex64(1.0, -0.5) / tm.Vec("f32", [1.0, 2.0, 3.0])
```

Python `int` → `usize`, `float` → `f64` by default.

### Loops and conditions

```python
loop_node = app.node("proc", func="process", factor=200,
                     loop=Loop("iter", factor=loop_factor))

cond_node = app.node("filter", func="filter_fn", factor=200,
                     condition=Condition(operation="Eq", value=1, value_type="usize",
                                        func="check_fn", args=[some_var]))
```

### Build options

```python
app.build(func_path="plugin/src/lib.rs",      # Rust source — auto-generates wrappers
          # or func_path="include/plugin.h",  # C header with // @tomii_export annotations
          plugin_manifest="plugin/Cargo.toml",
          release=True)
```

### Run options

```python
app.run(workers=8, system_threads=2, slots=4, max_frames=100,
        timing="timing.csv", report="report.json",
        inline_continuation=True, coalesce_barriers=True)
```

---

## Agent-native interfaces

Tomii exposes structured discovery and diagnostic interfaces designed for LLM agents.

### Discovery

```bash
python -m tomii --list-knobs           # all graph.run() options
python -m tomii --list-knobs-json      # machine-readable JSON with search hints
python -m tomii --schema               # JSON schema for the graph construction API
```

### Structured performance report

Pass `report="report.json"` to `app.run()` for a JSON performance report after each run:

| Key | Description |
|---|---|
| `summary.avg_latency_us` / `p50` / `p99` | Frame latency statistics |
| `summary.throughput_frames_per_sec` | End-to-end throughput |
| `summary.scheduling_overhead_diagnostic` | `overhead_pct`, `overhead_us`, interpretation |
| `per_node` | Per-node avg/p99 exec time, `on_critical_path` flag |
| `optimization_suggestions` | Prioritised list: category, action, knob, estimated speedup |

### Agent Skills

[`SKILLS/`](SKILLS/) contains structured workflow skills covering the full optimisation
lifecycle — from project discovery to graph coarsening:

| Skill | Purpose |
|---|---|
| `project-discover` | Orient in an unknown project: topology, knob inventory, baseline |
| `graph-build` | Translate a computation description into a graph + plugin stubs |
| `run-validate` | Build, verify correctness, establish baseline |
| `diagnose` | Classify bottleneck (scheduling / compute / imbalance) |
| `knob-search` | 5-iteration search over scheduler knobs using per-knob hints |
| `graph-coarsen` | Reduce task count when `overhead_pct > 60%` |
| `plugin-author` | Write correct `#[tomii_export]` Rust/C plugin functions |

```bash
./SKILLS/install-skills.sh            # installs to .claude/skills/ in CWD
```

---

## Graph visualisation

```bash
python -m tomii --visualize examples/stream-analytics/graph.json       # browser view
python -m tomii --visualize examples/stream-analytics/graph.json --edit # browser edit
python -m tomii --visualize graph.json --ascii                          # terminal ASCII
```

The web UI renders a colour-coded DAG (Dagre layout): green for compute nodes,
orange-bordered for conditional, gray for post-nodes. Edges are styled by type
(`$res` solid blue, `$dep` dashed, `$barrier` thick orange). **Export Python** downloads a
ready-to-run script from the current graph.

---

## JSON + CLI workflow

```
cargo run -p tomii-core --bin main -- \
  --json graph.json --dylib plugin.so \
  --workers 4 --slots 2 --max-frames 100
```

Key flags: `--workers`, `--slots`, `--system-threads`, `--timing`, `--report`,
`--fifo`, `--custom`, `--inline-continuation`, `--coalesce-barriers`,
`--resolution-strategy multi-slot-batch`.

Full flag list: `cargo run -p tomii-core --bin main -- --help`

---

## Pluggable scheduler

Implement the `TaskScheduler` trait (defined entirely in `tomii-types` — no `tomii-core`
dependency required) and load it at runtime:

```bash
cargo build --release -p scheduler-plugin
cargo run -p tomii-core --bin main -- \
  --scheduler-plugin target/release/libscheduler_plugin.so \
  --json graph.json --dylib plugin.so
```

See `examples/scheduler-plugin/` for a minimal FIFO example and
`tomii-core/PLUGIN_SCHEDULER_API.md` for the stability contract.

---

## Flagship examples

### Example #1 — Public 4×4 MIMO uplink benchmark

```bash
cd bench/mimo-bench
# requires Intel MKL, Agora sender (see README)
python tomii/run_bench.py --workers 4 --slots 4 --frames 200
python taskflow/run_bench.py --workers 4 --slots 4 --frames 200
```

Tomii dispatches FFT tasks as each UDP packet arrives; Taskflow must collect all packets
before submitting the full DAG. This packet-overlap is the structural advantage the
benchmark measures. See `bench/mimo-bench/README.md` for topology and metric.

### Example #2 — Multi-frame pipeline S-scaling

```bash
cd bench/pipeline-bench
python tomii/run_bench.py --workers 4 --slots 16 --frames 200
python taskflow/run_bench.py --workers 4 --slots 16 --frames 200
```

Sweeps concurrent-slot count (S) to show how per-frame scheduling overhead amortises
as multi-slot reuse takes effect. Run `run_bench.py` to generate the sweep CSV locally
(run outputs are not committed). See `bench/pipeline-bench/README.md` for the topology
and metric.

Tomii runs use `--custom --coalesce-barriers --inline-continuation` (hardcoded in `run_bench.py`);
these are the recommended flags for streaming workloads. Taskflow uses default `tf::Executor`.

### Ergonomics #1 — Agent-native graph tuning

```bash
cd examples/agent-tuning
bash run_all.sh 50   # runs all 4 arms (random, Bayesian, grid, Claude)
```

Four optimisation arms (random, Bayesian, grid, Claude) compete over the stream-analytics
knob space with the same budget (50 iterations) and verifier. The agent converges without
being given source code or documentation; an edit that drops a barrier or removes a `$dep`
edge fails the verifier and is rejected. See `examples/agent-tuning/README.md`.

### Ergonomics #2 — Polyglot plugin showcase

The same DAG (FFT + matrix compute) runs with Rust, C, and Python kernels:

```bash
python examples/matrix-compute/run_bench.py --workers 4
python examples/matrix-compute-C/run_bench.py --workers 4
python examples/matrix-compute-python/run_bench.py --workers 4
```

No source changes to the runtime — the plugin boundary is a C ABI, language-agnostic by
design. See `examples/README.md` for the full capability matrix.

---

## Architecture

**Workspace crates:**
- `tomii-core` — runtime, scheduler, graph engine, network receiver
- `tomii-types` — `CmTypes` enum + stable scheduler API types (`SchedulerPriority`, `SchedulerWorkerRange`, `CoreSpec`)
- `tomii-converter` — code-generation: wraps Rust/C plugin headers into `wrappers.rs`/`reg.rs`
- `tomii-macro` — procedural macros for plugin wrapping (WIP)
- `tomii/` — Python API package

**Key runtime modules (`tomii-core/src/runtime/`):**
- `resolution_loop.rs` — main resolution loop, batch draining
- `batch_resolution.rs` — four-phase batch processing (Phases 1–3)
- `resolution_strategy.rs` — `ResolutionStrategy` trait + `MultiSlotBatchStrategy`
- `task_execution.rs` — worker task execution, inline-continuation fast path
- `successor.rs` — successor collection and dependency propagation
- `shared_data.rs` — `SharedData`, `SlotData`, borrow bundles
- `slot_lifecycle.rs` — slot completion detection
- `ARCHITECTURE.md` — detailed threading model, memory ordering, invariants

**Threading model:**
- Worker threads (Rayon or custom pool) with CPU affinity — kernel execution
- System thread(s) — dependency propagation and slot lifecycle
- Network receiver threads — low-latency UDP/TCP packet ingestion (feature `network`)
- Async recorder thread — non-blocking timing output

See `tomii-core/src/runtime/ARCHITECTURE.md` for the performance envelope (intrinsic costs,
target workload classes, and workloads Tomii explicitly does not target).

---

## Build

```bash
cargo build --release
make schema   # regenerate Python bindings after changing json_structs.rs
```

> **Note for `bench/mimo-bench/` builds:** the MIMO bench links Intel MKL and Agora libs.
> Run `source examples/mimolib/scripts/export.sh` before building to set the required
> library paths. See `bench/mimo-bench/README.md` for the full dependency list.

## Environment variables

- `FUNC_PATH` — path to plugin header or Rust source (required for tomii-converter)
- `WRAP_PATH` / `REG_PATH` — wrapper/registry files (optional, auto-generated)

---

## License

[Apache License 2.0](LICENSE)

