Metadata-Version: 2.4
Name: tunerra-studio-tool
Version: 0.1.0
Summary: Profile, explain, and optimize algorithmic workloads from one developer CLI.
Author: Tunerra Studio Contributors
License: MIT
Keywords: performance,benchmark,algorithms,profiling,developer-tools
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: numpy
Requires-Dist: numpy>=1.24; extra == "numpy"
Provides-Extra: algoat
Requires-Dist: algoat>=0.1.0; extra == "algoat"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# Tunerra Studio

![tests](https://github.com/AyushPaul26/tunerra-studio/actions/workflows/tests.yml/badge.svg)
![python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)
![license](https://img.shields.io/badge/license-MIT-green)
![status](https://img.shields.io/badge/status-v0.1.0%20alpha-orange)

**Profile. Explain. Optimize.**

Tunerra Studio is an open-source developer CLI for finding algorithmic performance candidates in Python code, benchmarking sorting backends on representative data, explaining data-driven strategy recommendations, and building a local machine tuning profile.

> **Status:** v0.1.0 alpha. Tunerra reports evidence and heuristics; it does not claim a backend is faster until it is benchmarked on the current machine and workload.

---

## Quick install

```bash
pip install -e .
```

That's it. Python 3.10+ required. No third-party runtime dependencies.

---

## What works in v0.1

| Command | What it does |
|:---|:---|
| `tunerra scan` | Statically scans Python source with `ast`; scanned code is **not executed**. |
| `tunerra bench` | Validates and benchmarks sorting implementations with optional NumPy and Algoat backends. |
| `tunerra explain` | Profiles dataset size, ordering, duplicates, type, range — emits an explainable recommendation. |
| `tunerra tune` | Inspects hardware and saves a benchmark matrix to `~/.tunerra-studio/tuning-profile.json`. |
| `tunerra dashboard` | Opens a dependency-free local dashboard for recent scan/benchmark/tuning state. |
| `--json` flag | Available on scan, bench, explain, and tune for scripting and CI integration. |

---

## 30-second tour

### 1. Scan a real project

```bash
tunerra scan path/to/your/project
```

Tunerra detects sorting, searching, and NumPy call patterns and reports the exact file/line plus a recommendation.

**Example output:**

```
Tunerra Studio -- Scan
Scanned 20 Python file(s).

tests/test_benchmark.py:9  [high] sorted
  sorted(times)
  -> Benchmark this sort with `tunerra bench` when it is on a hot path.

tunerra_studio/benchmark/runner.py:34  [medium] method.sort
  values.sort()
  -> Check input size, ordering, and duplicate rate before optimizing.
```

### 2. Benchmark on this machine

```bash
tunerra bench --size 100000 --pattern nearly-sorted --repeat 5
```

**Example output:**

```
Tunerra Studio -- Benchmark
Dataset: random, 1,000 items, 1 run(s)
  python.list.sort         0.080 ms  (1.12x vs python.sorted)
  python.sorted            0.089 ms  (1.00x vs python.sorted)
Winner: python.list.sort
```

Supported generated patterns:

- `random`
- `duplicates`
- `sorted`
- `reverse`
- `nearly-sorted`

Backends are discovered at runtime. The core install always includes `python.sorted` and `python.list.sort`. If NumPy is installed, `numpy.sort` is included. If an installed `algoat` module exposes a callable `sort`, Tunerra includes it automatically.

Before timing a backend, Tunerra validates that it produces the same sorted output as Python's built-in `sorted`. Backend-specific input preparation (for example, creating a fresh list for an in-place sort) happens outside the timed region, so the reported numbers focus on the sorting operation rather than data-conversion cost.

### 3. Explain a dataset

Generated data:

```bash
tunerra explain --size 50000 --pattern duplicates
```

File input:

```bash
tunerra explain values.json
tunerra explain values.csv
tunerra explain values.npy   # requires NumPy
```

**Example output:**

```
Tunerra Studio -- Explain
  size               1000
  dtype              int
  sortedness         1.0
  duplicate_ratio    0.0
  numeric            True
  min                0
  max                999

Recommended strategy: python-timsort
  * Small inputs often favor Python's low-overhead built-in Timsort.
  * The input is highly ordered, a pattern Timsort can exploit.

This is a heuristic recommendation, not a proof of fastest performance on your machine.
```

Supported input formats are `.json` (top-level list), `.csv`, `.txt`, and `.npy`.

### 4. Tune the local machine

```bash
tunerra tune --quick
```

**Example output:**

```
Tunerra Studio -- Tune
System:
  system           Windows
  release          11
  machine          AMD64
  processor        Intel64 Family 6 Model 183 Stepping 1, GenuineIntel
  python           3.12.10
  logical_cpus     16
  memory_bytes     25463480320

Backend wins:
  python.list.sort     5
  python.sorted        1

Saved profile: C:\Users\you\.tunerra-studio\tuning-profile.json
```

Run the larger default matrix with:

```bash
tunerra tune
```

Inspect hardware only:

```bash
tunerra tune --system-only
```

### 5. Open the local dashboard

```bash
tunerra dashboard
```

Default URL: `http://127.0.0.1:8765`

The dashboard only serves local state generated by Tunerra. Bind to another host only if you understand the network exposure.

---

## Installation

Python 3.10+ is required.

```bash
# Core install (zero runtime dependencies)
pip install -e .

# With NumPy support
pip install -e ".[numpy]"

# With the optional Algoat backend adapter
pip install -e ".[algoat]"

# For development and tests
pip install -e ".[dev,numpy]"
pytest
```

> **Note:** The `tunerra` command is registered as a console entry point during `pip install`. If you skip the install step and run scripts directly, use `python -m tunerra_studio.cli` instead.

---

## CI / Scripting integration

All major commands support `--json` output for easy integration with CI pipelines, scripts, and other tools:

```bash
tunerra bench --size 10000 --json
tunerra scan . --json
tunerra explain --size 5000 --json
tunerra tune --system-only --json
```

**Example: GitHub Actions step**

```yaml
- run: pip install -e .
- run: tunerra scan . --json > scan-results.json
- run: tunerra bench --size 10000 --json > bench-results.json
```

---

## Scanner safety

`tunerra scan` reads source files and parses them with Python's standard-library AST parser. It does **not** import or execute the scanned project.

Folders such as `.git`, `.venv`, `venv`, `node_modules`, `__pycache__`, `build`, and `dist` are skipped.

## How recommendations work

The v0.1 explain engine intentionally uses transparent heuristics rather than pretending it has perfect knowledge. It looks at traits such as:

- dataset size
- sampled sortedness
- duplicate ratio
- whether values are numeric
- observed min/max where comparable

Tunerra then emits scores and human-readable reasons. Use `tunerra bench` with representative data before making performance changes.

## Optional backends

The core package has no runtime third-party dependency. Optional backends are loaded only when available.

This makes it possible to add future adapters without forcing every user to install every numerical or native library. Optional backends are treated as untrusted benchmark participants: they must return a correct result or Tunerra records them under `skipped`.

## Local data

Tunerra stores its generated local state in:

```text
~/.tunerra-studio/
```

Current files may include:

```text
last-scan.json
last-benchmark.json
last-explain.json
tuning-profile.json
```

Set `TUNERRA_HOME` to override that directory. Tunerra Studio v0.1 does not include telemetry or upload benchmark/scan data to a remote service.

---

## Repository layout

```text
tunerra-studio/
├── tunerra_studio/
│   ├── analyzer/      # AST scanner
│   ├── benchmark/     # benchmark runner
│   ├── dashboard/     # local web UI
│   ├── explain/       # dataset profiler + strategy engine
│   ├── tune/          # hardware + tuning matrix
│   ├── cli.py
│   └── utils.py
├── tests/
├── docs/
│   ├── architecture.md
│   ├── roadmap.md
│   └── releasing.md
├── .github/
│   ├── workflows/tests.yml
│   ├── ISSUE_TEMPLATE/
│   └── PULL_REQUEST_TEMPLATE.md
├── pyproject.toml
├── CONTRIBUTING.md
├── SECURITY.md
├── CHANGELOG.md
└── LICENSE
```

---

## Development

```bash
git clone <your-repository-url>
cd tunerra-studio
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\\Scripts\\activate
pip install -e ".[dev,numpy]"
pytest
```

Try the CLI:

```bash
tunerra --version
tunerra bench --size 1000 --repeat 1
tunerra explain --size 1000 --pattern sorted
tunerra tune --system-only
```

---

## Troubleshooting

| Problem | Solution |
|:---|:---|
| `tunerra: command not found` | You need to install the package first: `pip install -e .` — the `tunerra` command is registered during installation. As a workaround, use `python -m tunerra_studio.cli` instead. |
| `ModuleNotFoundError: No module named 'tunerra_studio'` | Run `pip install -e .` from the repo root, or use `python -m pytest` instead of bare `pytest`. |
| `numpy.sort` not appearing in benchmarks | Install NumPy: `pip install -e ".[numpy]"` |
| Dashboard won't start / port in use | Try a different port: `tunerra dashboard --port 9000` |
| `tunerra scan` crashes with encoding error | Update to the latest version — this was fixed by replacing Unicode symbols with ASCII equivalents. |

---

## Roadmap

See [`docs/roadmap.md`](docs/roadmap.md).

The next milestones focus on safer code fixes, persistent benchmark history, richer operation detection, editor integrations, and pluggable backends.

## Contributing

Contributions are welcome. See [`CONTRIBUTING.md`](CONTRIBUTING.md).

## Releasing

See [`docs/releasing.md`](docs/releasing.md) for steps to publish a new version.

## License

MIT — see [`LICENSE`](LICENSE).
