Metadata-Version: 2.4
Name: wolfram-boost
Version: 0.1.0
Summary: A transparent turbocharger for wolframclient.
Author: TurinFohlen
Author-email: TurinFohlen <turin@example.com>
License: MIT
Project-URL: Homepage, https://github.com/TurinFohlen/wolfram-boost
Project-URL: Issues, https://github.com/TurinFohlen/wolfram-boost/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.20
Requires-Dist: wolframclient
Dynamic: author
Dynamic: requires-python

# wolfram-boost

**A transparent turbocharger for wolframclient. One import, zero API changes.**

[![PyPI version](https://badge.fury.io/py/wolfram-boost.svg)](https://pypi.org/project/wolfram-boost/)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

The official wolframclient gets sluggish with anything beyond tiny data—an 8 MB image takes 1.5 seconds, a short audio clip takes seconds.
`wolfram-boost` swaps out the transport layer so the same data arrives in tens of milliseconds.

No API changes. No new concepts. Just a smoother experience.

---

## The difference

| Data size | Official | wolfram-boost | Feels like |
|-----------|----------|---------------|------------|
| Tiny | 7 ms | 14 ms | Same |
| Small | 37 ms | 9 ms | Snappier |
| Medium | 161 ms | 17 ms | Smooth |
| Image (8 MB) | 1.5 s | 50 ms | Lag is gone |
| Large image (32 MB) | 5.8 s | 246 ms | Actually usable |
| Heavy (80 MB+) | Unusable | Under 0.5 s | Feels local |

> Benchmarks: ARM64 Linux, Wolfram Engine 14.3, 20-round median.

---

## Installation

```bash
pip install wolfram-boost
```

Requirements:

· Python ≥ 3.8
· NumPy ≥ 1.20
· wolframclient
· Wolfram Engine or Mathematica installed and configured
· Linux only (relies on /dev/shm)

---

Quick start

```python
# Before
from wolframclient.evaluation import WolframLanguageSession

# After
from wolfram_boost import SHMWolframSession

session = SHMWolframSession(
    kernel="/opt/Wolfram/WolframEngine/14.3/Executables/WolframKernel"
)

# Everything else is the same
from wolframclient.language import wl
import numpy as np

img = np.random.rand(4096, 4096, 3).astype(np.float32)
result = session.evaluate(wl.ImageMeasurements(img, "MeanIntensity"))

audio = np.random.randint(-32768, 32767, size=(2, 44100), dtype=np.int16)
result = session.evaluate(wl.Mean(wl.Flatten(audio)))

small = np.random.rand(100, 2)
result = session.evaluate(wl.Mean(wl.Flatten(small)))

session.terminate()
```

---

How it works

You don't need to know. But if you're curious:

```
Your data
    │
    ├── small → normal ZMQ path (no overhead)
    │
    └── large → high-speed bypass → Wolfram Engine
                    │
              files cleaned up automatically
```

The decision is automatic. You can tweak the threshold if you want:

```python
session = SHMWolframSession(kernel="...", threshold=10*1024)  # 10 KB
```

---

Supported data types

Everything you're likely to throw at Wolfram Engine:

float32 · float64 · float16 · int8 · int16 · int32 · int64 · uint8 · uint16 · uint32 · uint64 · complex64 · complex128 · bool

---

API

SHMWolframSession is a drop-in replacement for WolframLanguageSession. Same methods, same signatures. You can also use the alias BoostSession if you prefer:

```python
from wolfram_boost import BoostSession
```

---

Limitations

· Linux only (uses /dev/shm)
· Python and Wolfram Engine must run on the same machine
· For multi-GB arrays, call np.ascontiguousarray() first

---

Tests

```bash
# Functional smoke test (all data types, cleanup verification)
python3 tests/smoke_test.py

# Benchmark (SHM vs ZMQ)
python3 tests/benchmark_shm_vs_zmq.py

# Extreme stress test (up to 512 MB+)
python3 tests/benchmark_hell.py
```

---

License

MIT
