Metadata-Version: 2.4
Name: runscope
Version: 0.1.0
Summary: Calibrated ETAs and completion intelligence for long-running jobs (a smarter progress bar).
Author: RunScope
License: Apache-2.0
Project-URL: Homepage, https://runscope.dev
Project-URL: Documentation, https://runscope.dev/docs
Project-URL: Source, https://github.com/runscope/runscope
Project-URL: Issues, https://github.com/runscope/runscope/issues
Project-URL: Changelog, https://github.com/runscope/runscope/blob/main/CHANGELOG.md
Keywords: progress,progress-bar,eta,estimation,tqdm,remaining-time,cli,data-processing,hpc,runtime
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: cloud
Requires-Dist: requests>=2.25; extra == "cloud"
Dynamic: license-file

# RunScope

**A progress bar that doesn't lie.** Calibrated ETAs and completion intelligence for
long-running Python jobs.

```python
from runscope import trange           # drop-in for tqdm

for i in trange(48000, key="terrain_analysis"):
    process(tile(i))
```

```
terrain_analysis  ▕████████░░░░░░░░░░░░▏ 38%  17,492/48,000
  47m elapsed · about 1h 20m left · done ~10:42 PM
  likely 1h 12m–1h 31m · confidence high
```

Ordinary progress bars assume the rest of your job looks like the part that already
ran. That assumption breaks exactly when it matters — when the expensive work is at
the end. RunScope gives you an **honest range** instead of a fake exact number, and it
**learns your recurring jobs** so each run's estimate gets better than the last.

---

## Install

```bash
pip install runscope        # free, local, zero dependencies
```

## Use it

### 1. Wrap any loop

```python
import runscope

for item in runscope.track(items, key="my_job"):
    process(item)
```

### 2. Drop-in for tqdm

```python
from runscope import trange
for i in trange(10000, key="my_job"):
    ...
```

### 3. Tell it how "big" each item is (stronger estimates)

```python
for path in runscope.track(files, key="ingest", weight=lambda p: p.stat().st_size):
    process(path)
```

### 4. Peek at the future for known-heterogeneous jobs

```python
# checks a tiny representative sample of the REMAINING work up front, so a
# back-loaded job can't ambush you with a 3x longer runtime at the end
for item in runscope.track(items, key="my_job", weight=size_of, measure=True):
    process(item)
```

### 5. Instrument an existing script without editing it

```bash
runscope run train.py        # transparently upgrades tqdm bars in the script
```

---

## How it works (you never have to think about this)

Three layers combine automatically:

| Layer | What it does | When it kicks in |
|-------|--------------|------------------|
| **Now** | size-weighted estimate from the current run | always |
| **Memory** | learns how *this* job actually behaves and calibrates | after ~3 runs of the same `key` |
| **Peek** | samples a little of the *remaining* work to catch heavy tails | `measure=True` |

The `key` is what ties runs of the same job together so RunScope can learn. Use a
stable name for recurring jobs (`key="nightly_terrain"`).

## Free vs Pro

- **Free**: local calibrated ETAs, honest ranges, and per-job history on your machine.
  No account, no network, no dependencies.
- **Pro** (coming): cloud history across machines, "today vs your last 20 runs," and
  push/Slack alerts when a job blows past its ETA or stalls.

## What it's good at (and what it isn't)

RunScope is for **enumerable** work — loops over files, records, images, tiles,
simulations, parameter grids, API calls. That covers a huge amount of scientific and
data-processing work.

It does **not** try to predict the runtime of an arbitrary opaque operation with no
sub-steps and no history. When there isn't enough information to estimate honestly,
it tells you so instead of inventing a number. That restraint is on purpose.

## The science

RunScope's estimators are not heuristics someone made up. They come from a research
program (ETA-Proto) that tested dozens of ETA methods against a simple baseline under
preregistered pass/fail gates and kept only what won by a required margin. The core
finding: for enumerable jobs, a size-weighted estimate is very hard to beat — except
by measuring a small sample of the *unexecuted* work, which cut remaining-time error
40–90% on hard, heterogeneous workloads. That measurement is the `measure=True` mode.

## License

Apache-2.0.
