tomii-rt 1.0.0__tar.gz

tomii_rt-1.0.0/Cargo.toml

@@ -0,0 +1,29 @@
+[workspace]
+members = ["tomii-types", "tomii/_python_bridge"]
+exclude = [
+    # Pure-C examples: no Rust source; built with Make, not Cargo.
+    "examples/matrix-compute-C",
+    "examples/mapreduce",
+    "examples/gpu-vectoradd",
+    # Pure-Python examples: no Rust source; bridge is in tomii/_python_bridge/.
+    "examples/matrix-compute-python",
+    # Stale worktree remnant from a prunable branch; exclude to avoid broken path dep.
+    "examples/.mimolib",
+    # agent-tuning has no Cargo.toml (Python/shell harness only).
+    "examples/agent-tuning",
+]
+resolver = "3"
+
+# Shared metadata inherited by the publishable crates via `field.workspace = true`.
+[workspace.package]
+version = "1.0.0"
+edition = "2021"
+license = "Apache-2.0"
+authors = ["Τομί Team"]
+repository = "https://github.com/Giotyp/Tomii"
+
+[profile.release]
+opt-level = 3
+debug = false 
+lto = "thin"
+codegen-units = 1

tomii_rt-1.0.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Τομί Team
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

tomii_rt-1.0.0/PKG-INFO

@@ -0,0 +1,331 @@
+Metadata-Version: 2.4
+Name: tomii-rt
+Version: 1.0.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: matplotlib>=3.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'
+Provides-Extra: agent-tuning
+Provides-Extra: dev
+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
+
+# Τομί (Tomii)
+
+**Task-graph framework for streaming pipelines, MIMO workloads, and agent-tuneable applications.**
+
+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-stream
+micro-task DAGs where dispatch overhead dominates, Taskflow is faster. Tomii's advantage
+is in workloads that benefit from concurrent streams, 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
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+### 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_streams=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` | Stream latency statistics |
+| `summary.throughput_streams_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-streams 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 --streams 200
+python taskflow/run_bench.py --workers 4 --slots 4 --streams 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-stream pipeline S-scaling
+
+```bash
+cd bench/pipeline-bench
+python tomii/run_bench.py --workers 4 --slots 16 --streams 200
+python taskflow/run_bench.py --workers 4 --slots 16 --streams 200
+```
+
+Sweeps concurrent-slot count (S) to show how per-stream 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)
+