modal-progress 0.1.0__py3-none-any.whl

modal_progress/__init__.py

@@ -0,0 +1,7 @@
+"""Live progress from inside Modal containers."""
+
+from .container import bar, report
+from .watch import Watcher, watch
+
+__all__ = ["bar", "report", "watch", "Watcher"]
+__version__ = "0.1.0"

modal_progress/__main__.py

@@ -0,0 +1,63 @@
+"""python -m modal_progress run app.py   modal run, plus plain progress lines in logs
+python -m modal_progress demo         a simulated fan-out, no Modal account needed
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+def demo(args: argparse.Namespace) -> None:
+    from .sim import simulate
+    from .watch import watch
+
+    fail = tuple(int(x) for x in args.fail.split(",") if x)
+    with watch(name="work", mode=args.mode, interval=args.interval) as w:
+        for _ in w.track(
+            simulate(inputs=args.inputs, containers=args.containers, steps=args.steps, step_time=args.step_time, fail=fail),
+            total=args.inputs,
+        ):
+            pass
+
+
+def run(rest: list[str], interval: float) -> None:
+    import modal.__main__
+
+    from .agent import install
+
+    install(interval=interval)
+    sys.argv = ["modal", "run", *rest]
+    modal.__main__.main()
+
+
+def main(argv: list[str] | None = None) -> None:
+    argv = sys.argv[1:] if argv is None else argv
+    # Everything after `run` goes to modal untouched, flags included.
+    if argv[:1] == ["run"]:
+        rest = argv[1:]
+        interval = 5.0
+        if rest[:1] == ["--interval"] and len(rest) > 1:
+            interval, rest = float(rest[1]), rest[2:]
+        return run(rest, interval)
+
+    parser = argparse.ArgumentParser(prog="modal-progress")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("run", help="modal run with plain progress lines (args go to modal run)")
+
+    d = sub.add_parser("demo", help="simulate a fan-out locally")
+    d.add_argument("--inputs", type=int, default=60)
+    d.add_argument("--containers", type=int, default=6)
+    d.add_argument("--steps", type=int, default=40)
+    d.add_argument("--step-time", type=float, default=0.1)
+    d.add_argument("--fail", default="37", help="comma-separated inputs that raise")
+    d.add_argument("--mode", choices=["rich", "plain"], default=None)
+    d.add_argument("--interval", type=float, default=None, help="seconds between plain lines")
+
+    args = parser.parse_args(argv)
+    if args.cmd == "demo":
+        demo(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

modal_progress/agent.py

@@ -0,0 +1,80 @@
+"""Plain map progress for `modal run` when nobody is at a terminal.
+
+Modal tracks map progress with its own counter and draws it as a rich live
+bar. When stdout is a file or a pipe, which is how a background agent runs
+it, rich draws nothing until the end, so the log has no progress at all.
+install() wraps that counter so it also prints a throttled plain line.
+No change to the user's code is needed.
+"""
+
+from __future__ import annotations
+
+import sys
+import time
+from typing import Callable, TextIO
+
+from .render import PREFIX
+from .state import clock
+
+
+class LineThrottle:
+    """Turns (completed, total) updates into at most one line per interval."""
+
+    def __init__(self, tag: str, interval: float = 5.0, out: TextIO | None = None, now=time.monotonic):
+        self.tag = tag
+        self.interval = interval
+        self.out = out
+        self.now = now
+        self.started = now()
+        self.last = self.started
+        self.last_line: tuple[int, int] | None = None
+
+    def __call__(self, completed: int, total: int) -> None:
+        t = self.now()
+        finished = total > 0 and completed >= total
+        if (completed, total) == self.last_line:
+            return
+        if not finished and t - self.last < self.interval:
+            return
+        self.last = t
+        self.last_line = (completed, total)
+        elapsed = t - self.started
+        if finished:
+            line = f"{PREFIX} {self.tag} {completed}/{total} done, {clock(elapsed)}"
+        else:
+            pct = f" ({100 * completed / total:.0f}%)" if total else ""
+            rate = completed / elapsed if elapsed > 0 else 0
+            # One finished input says little about the rest, so wait for 5%.
+            trusted = total and completed >= max(2, total * 0.05)
+            eta = f", eta {clock((total - completed) / rate)}" if rate > 0 and trusted else ""
+            line = f"{PREFIX} {self.tag} {completed}/{total} done{pct}, {clock(elapsed)} elapsed{eta}"
+        out = self.out or sys.stdout
+        out.write(line + "\n")
+        out.flush()
+
+
+def install(interval: float = 5.0, manager_cls=None) -> Callable[[], None]:
+    """Patches Modal's rich output manager. Returns a function that undoes it."""
+    if manager_cls is None:
+        from modal._output.rich import RichOutputManager as manager_cls
+
+    original = manager_cls.function_progress_callback
+
+    def function_progress_callback(self, tag: str, total: int | None):
+        update = original(self, tag, total)
+        if self.is_terminal:
+            return update
+        line = LineThrottle(tag, interval)
+
+        def both(completed: int, total: int) -> None:
+            update(completed, total)
+            line(completed, total)
+
+        return both
+
+    manager_cls.function_progress_callback = function_progress_callback
+
+    def undo() -> None:
+        manager_cls.function_progress_callback = original
+
+    return undo

modal_progress/container.py

@@ -0,0 +1,236 @@
+"""Container side: ship progress events to whoever is watching the map.
+
+Events go to one named Modal Queue, in a partition keyed by the app ID, so
+the caller can find them without any change to the function's signature.
+A background thread batches them, keeping only the latest event per bar,
+so a tight loop never waits on the network.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import threading
+import time
+from typing import Callable
+
+QUEUE_NAME = "modal-progress"
+PARTITION_TTL = 3600
+FLUSH_EVERY = 0.25
+
+# Set by watch() for in-process runs (the simulator and tests).
+_local_sink: Callable[[dict], None] | None = None
+_task_override = threading.local()
+
+
+def set_local_sink(sink: Callable[[dict], None] | None) -> None:
+    global _local_sink
+    _local_sink = sink
+
+
+def disabled() -> bool:
+    return os.environ.get("MODAL_PROGRESS", "").lower() == "off"
+
+
+def task_id() -> str:
+    override = getattr(_task_override, "task", None)
+    if override:
+        return override
+    return os.environ.get("MODAL_TASK_ID") or "local"
+
+
+def input_id() -> str | None:
+    # Inside a container modal is already loaded. Elsewhere, importing it
+    # just to learn there is no input would cost a second.
+    modal = sys.modules.get("modal")
+    if modal is None:
+        return None
+    try:
+        return modal.current_input_id()
+    except Exception:
+        return None
+
+
+def _remote_target():
+    """The queue and partition key to send to, or (None, None) outside Modal."""
+    if os.environ.get("MODAL_IS_REMOTE") != "1":
+        return None, None
+    import modal
+
+    key = os.environ.get("MODAL_PROGRESS_KEY")
+    if not key:
+        app = modal.App._get_container_app()
+        key = app.app_id if app is not None else None
+    if not key:
+        return None, None
+    return modal.Queue.from_name(QUEUE_NAME, create_if_missing=True), key
+
+
+class _Sender:
+    def __init__(self) -> None:
+        self._pending: dict[str, dict] = {}
+        self._lock = threading.Lock()
+        self._wake = threading.Event()
+        self._sent = threading.Condition(self._lock)
+        self._queued = 0  # events handed to send()
+        self._done = 0  # events that have left the process
+        self._thread: threading.Thread | None = None
+        self._target = None
+
+    def send(self, ev: dict) -> None:
+        with self._lock:
+            self._pending[ev["id"]] = ev
+            self._queued += 1
+            if self._thread is None:
+                self._thread = threading.Thread(target=self._run, name="modal-progress", daemon=True)
+                self._thread.start()
+
+    def flush(self, timeout: float = 2.0) -> None:
+        """Waits until the events sent before this call have left the process.
+
+        Only those: other threads may keep sending, and waiting for an empty
+        buffer would stall every input while any container is busy.
+        """
+        with self._lock:
+            target = self._queued
+        self._wake.set()
+        with self._sent:
+            self._sent.wait_for(lambda: self._done >= target, timeout=timeout)
+
+    def _run(self) -> None:
+        while True:
+            self._wake.wait(FLUSH_EVERY)
+            self._wake.clear()
+            with self._lock:
+                batch = list(self._pending.values())
+                self._pending.clear()
+                upto = self._queued
+            if batch:
+                self._put(batch)
+            with self._sent:
+                self._done = upto
+                self._sent.notify_all()
+
+    def _put(self, batch: list[dict]) -> None:
+        # Progress must never break the job, so every failure here is swallowed.
+        try:
+            if _local_sink is not None:
+                for ev in batch:
+                    _local_sink(ev)
+                return
+            if self._target is None:
+                self._target = _remote_target()
+            queue, key = self._target
+            if queue is not None:
+                queue.put_many(batch, partition=key, partition_ttl=PARTITION_TTL)
+        except Exception:
+            pass
+
+
+_sender = _Sender()
+
+
+class bar:
+    """A tqdm-style bar that reports to the caller instead of a terminal.
+
+        for step in bar(range(100), desc=f"input {i}"):
+            ...
+
+    Updates are sent at most once every `every` seconds, plus the first and
+    the last, so wrapping a fast loop costs almost nothing.
+    """
+
+    def __init__(self, iterable=None, total: float | None = None, desc: str = "", every: float = 0.5):
+        if total is None and iterable is not None:
+            try:
+                total = len(iterable)
+            except TypeError:
+                total = None
+        self.iterable = iterable
+        self.total = total
+        self.desc = desc
+        self.every = every
+        self.n: float = 0
+        self.closed = False
+        self.id = os.urandom(4).hex()
+        self._last = 0.0
+        self._off = disabled()  # read once: os.environ costs a microsecond per lookup
+        self._emit(force=True)
+
+    def __iter__(self):
+        # The hot path, so the throttle check is inlined.
+        clock = time.monotonic
+        try:
+            for item in self.iterable:
+                yield item
+                self.n += 1
+                if not self._off and clock() - self._last >= self.every:
+                    self._emit(force=True)
+        finally:
+            self.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+
+    def update(self, k: float = 1) -> None:
+        self.n += k
+        self._emit()
+
+    def set_description(self, desc: str) -> None:
+        self.desc = desc
+        self._emit()
+
+    def close(self) -> None:
+        if self.closed:
+            return
+        self.closed = True
+        self._emit(force=True)
+        if not self._off:
+            _sender.flush()
+
+    def _emit(self, force: bool = False) -> None:
+        if self._off:
+            return
+        now = time.monotonic()
+        if not force and now - self._last < self.every:
+            return
+        self._last = now
+        _sender.send(
+            {
+                "id": self.id,
+                "task": task_id(),
+                "input": input_id(),
+                "desc": self.desc,
+                "n": self.n,
+                "total": self.total,
+                "done": self.closed,
+                "t": time.time(),
+            }
+        )
+
+
+_manual: dict[str | None, bar] = {}
+
+
+def report(n: float, total: float | None = None, desc: str = "") -> None:
+    """Sets progress for the current input directly, for loops bar() can't wrap.
+
+    The bar closes itself once n reaches total.
+    """
+    key = input_id()
+    b = _manual.get(key)
+    if b is None or b.closed:
+        b = _manual[key] = bar(total=total, desc=desc)
+    if total is not None:
+        b.total = total
+    if desc:
+        b.desc = desc
+    b.n = n
+    if b.total and n >= b.total:
+        b.close()
+        _manual.pop(key, None)
+    else:
+        b._emit()

modal_progress/render.py

@@ -0,0 +1,175 @@
+"""Two ways to draw a State: plain lines for logs and agents, rich bars for people."""
+
+from __future__ import annotations
+
+import sys
+import threading
+from typing import TextIO
+
+from .state import State, clock
+
+PREFIX = "[progress]"
+
+
+def plain_line(state: State, now: float | None = None) -> str:
+    name = state.name
+    if state.finished is not None:
+        counts = f"{state.done}/{state.total}" if state.total else f"{state.done}"
+        return f"{PREFIX} {name} finished: {counts} done, {state.failed} failed, {clock(state.elapsed())}"
+    parts = []
+    if state.total:
+        pct = 100 * state.done / state.total
+        parts.append(f"{name} {state.done}/{state.total} done ({pct:.0f}%)")
+    else:
+        parts.append(f"{name} {state.done} done")
+    parts.append(f"{state.failed} failed")
+    if state.bars:
+        parts.append(f"{state.busy(now)} running")
+    parts.append(f"{clock(state.elapsed(now))} elapsed")
+    eta = state.eta(now)
+    if eta is not None:
+        parts.append(f"eta {clock(eta)}")
+    return f"{PREFIX} " + ", ".join(parts)
+
+
+class PlainRenderer:
+    """Prints one line every `interval` seconds, plus failures as they happen.
+
+    Lines have a fixed shape so an agent reading the log can grep them.
+    """
+
+    def __init__(self, state: State, lock: threading.Lock, out: TextIO | None = None, interval: float = 5.0):
+        self.state = state
+        self.lock = lock
+        self.out = out or sys.stdout
+        self.interval = interval
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+
+    def start(self) -> None:
+        self._thread = threading.Thread(target=self._run, name="modal-progress-plain", daemon=True)
+        self._thread.start()
+
+    def _run(self) -> None:
+        while not self._stop.wait(self.interval):
+            self.tick()
+
+    def _write(self, line: str) -> None:
+        self.out.write(line + "\n")
+        self.out.flush()
+
+    def tick(self, now: float | None = None) -> None:
+        with self.lock:
+            line = plain_line(self.state, now)
+        self._write(line)
+
+    def failure(self, error: str) -> None:
+        self._write(f"{PREFIX} {self.state.name}: an input failed: {error}")
+
+    def close(self) -> None:
+        self._stop.set()
+        if self._thread is not None:
+            self._thread.join(timeout=1)
+        self.tick()
+
+
+def rich_view(state: State, now: float | None = None):
+    """One overall bar, then one row per container that is still reporting."""
+    from rich.progress_bar import ProgressBar
+    from rich.table import Table
+    from rich.text import Text
+
+    grid = Table.grid(padding=(0, 1))
+    grid.add_column(no_wrap=True)
+    grid.add_column(no_wrap=True, min_width=14)
+    grid.add_column(width=32)
+    grid.add_column(justify="right", no_wrap=True)
+    grid.add_column(no_wrap=True)
+
+    total = state.total or max(state.done, 1)
+    eta = state.eta(now)
+    tail = Text(clock(state.elapsed(now)), style="cyan")
+    if eta is not None:
+        tail.append(f"  eta {clock(eta)}", style="dim")
+    if state.failed:
+        tail.append(f"  {state.failed} failed", style="red")
+    grid.add_row(
+        Text(state.name, style="bold"),
+        Text(f"{state.busy(now)} running", style="dim"),
+        ProgressBar(total=total, completed=state.effective(now), width=32, complete_style="green"),
+        Text(f"{state.done}/{state.total if state.total else '?'}"),
+        tail,
+    )
+    for b in state.active(now):
+        short = b.task[-6:]
+        bar = ProgressBar(
+            total=b.total or 1,
+            completed=b.n if b.total else 0,
+            pulse=not b.total and not b.done,
+            width=32,
+            complete_style="grey50" if b.done else "magenta",
+        )
+        count = f"{b.n:g}/{b.total:g}" if b.total else f"{b.n:g}"
+        grid.add_row(
+            Text(f"  {short}", style="dim"),
+            Text(b.desc or "", style="grey50" if b.done else ""),
+            bar,
+            Text(count, style="dim"),
+            Text("idle" if b.done else "", style="dim"),
+        )
+    return grid
+
+
+class RichRenderer:
+    """Live bars in a terminal.
+
+    Under `modal run`, Modal already has a live display on screen, and two
+    live displays fight over the cursor. So the view joins Modal's own
+    display when there is one, and opens its own otherwise.
+    """
+
+    def __init__(self, state: State, lock: threading.Lock, console=None):
+        self.state = state
+        self.lock = lock
+        self.console = console
+        self._live = None
+        self._group = None
+
+    def __rich__(self):
+        with self.lock:
+            return rich_view(self.state)
+
+    def start(self) -> None:
+        self._group = _modal_render_group()
+        if self._group is not None:
+            self._group.renderables.append(self)
+            return
+        from rich.live import Live
+
+        self._live = Live(self, console=self.console, refresh_per_second=4, transient=False)
+        self._live.start()
+
+    def failure(self, error: str) -> None:
+        pass  # the failed count is on the overall row
+
+    def close(self) -> None:
+        if self._live is not None:
+            self._live.stop()
+            return
+        if self._group is not None and self in self._group.renderables:
+            self._group.renderables.remove(self)
+        from rich.console import Console
+
+        with self.lock:
+            line = plain_line(self.state)
+        (self.console or Console()).print(line, highlight=False)
+
+
+def _modal_render_group():
+    """Modal's live render group, if a `modal run` display is up. Private API, so guarded."""
+    try:
+        from modal._output.manager import OutputManager
+
+        return getattr(OutputManager.get(), "_current_render_group", None)
+    except Exception:
+        return None

modal_progress/sim.py

@@ -0,0 +1,49 @@
+"""A fake fan-out that runs on threads, so the display can be tried without Modal.
+
+Each thread plays one container: it pulls inputs, walks a bar() for each,
+and raises on the inputs listed in `fail`. Results come back in completion
+order, like `.map(..., order_outputs=False, return_exceptions=True)`.
+"""
+
+from __future__ import annotations
+
+import random
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from typing import Iterator
+
+from . import container
+from .container import bar
+
+
+def simulate(
+    inputs: int = 60,
+    containers: int = 6,
+    steps: int = 40,
+    step_time: float = 0.1,
+    fail: tuple[int, ...] = (37,),
+    seed: int = 0,
+) -> Iterator:
+    rng = random.Random(seed)
+    # Some inputs are slower than others, as in a real map.
+    speed = [rng.uniform(0.6, 1.6) for _ in range(inputs)]
+    names = iter(f"sim-{k:02d}-{rng.getrandbits(24):06x}" for k in range(containers))
+    names_lock = threading.Lock()
+
+    def boot():
+        with names_lock:
+            container._task_override.task = next(names)
+
+    def work(i: int) -> int:
+        for step in bar(range(steps), desc=f"input {i}", every=0.2):
+            time.sleep(step_time * speed[i])
+            if i in fail and step == steps * 2 // 3:
+                raise ValueError(f"bad input {i}")
+        return i * i
+
+    with ThreadPoolExecutor(max_workers=containers, initializer=boot) as pool:
+        futures = [pool.submit(work, i) for i in range(inputs)]
+        for f in as_completed(futures):
+            e = f.exception()
+            yield e if e is not None else f.result()

modal_progress/state.py

@@ -0,0 +1,102 @@
+"""Folds progress events into one snapshot that the renderers draw."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+
+# A container that has sent nothing for this long drops off the display.
+STALE_AFTER = 15.0
+
+
+@dataclass
+class Bar:
+    id: str
+    task: str
+    desc: str = ""
+    n: float = 0
+    total: float | None = None
+    done: bool = False
+    seen: float = 0.0
+
+    @property
+    def fraction(self) -> float | None:
+        if not self.total:
+            return None
+        return max(0.0, min(self.n / self.total, 1.0))
+
+
+@dataclass
+class State:
+    name: str = "map"
+    total: int | None = None
+    done: int = 0
+    failed: int = 0
+    started: float = field(default_factory=time.monotonic)
+    finished: float | None = None
+    bars: dict[str, Bar] = field(default_factory=dict)  # latest bar per container
+    first_seen: dict[str, float] = field(default_factory=dict)
+    last_error: str | None = None
+
+    def apply(self, ev: dict, now: float | None = None) -> None:
+        """Takes one event sent by bar() inside a container."""
+        now = time.monotonic() if now is None else now
+        task = ev.get("task") or "local"
+        self.first_seen.setdefault(task, now)
+        bar = self.bars.get(task)
+        if bar is None or bar.id != ev["id"]:
+            bar = self.bars[task] = Bar(id=ev["id"], task=task)
+        bar.desc = ev.get("desc") or ""
+        bar.n = ev.get("n", 0)
+        bar.total = ev.get("total")
+        bar.done = bool(ev.get("done"))
+        bar.seen = now
+
+    def result(self, ok: bool, error: str | None = None) -> None:
+        """Counts one finished input from the map's result stream."""
+        self.done += 1
+        if not ok:
+            self.failed += 1
+            self.last_error = error
+
+    def active(self, now: float | None = None) -> list[Bar]:
+        """Bars from containers that are still sending, oldest container first."""
+        now = time.monotonic() if now is None else now
+        live = [b for b in self.bars.values() if now - b.seen < STALE_AFTER]
+        return sorted(live, key=lambda b: self.first_seen[b.task])
+
+    def busy(self, now: float | None = None) -> int:
+        return sum(1 for b in self.active(now) if not b.done)
+
+    def elapsed(self, now: float | None = None) -> float:
+        end = self.finished if self.finished is not None else (time.monotonic() if now is None else now)
+        return max(0.0, end - self.started)
+
+    def effective(self, now: float | None = None) -> float:
+        """Finished inputs plus the finished share of the ones still running."""
+        partial = sum(b.fraction or 0.0 for b in self.active(now) if not b.done)
+        value = self.done + partial
+        return min(value, self.total) if self.total else value
+
+    def eta(self, now: float | None = None) -> float | None:
+        # Too early to say until 5% of inputs are back.
+        if not self.total or self.finished is not None or self.done < max(1, self.total * 0.05):
+            return None
+        now = time.monotonic() if now is None else now
+        progress = self.effective(now)
+        # Time from the first container event, so the cold start doesn't count as work.
+        began = min(self.first_seen.values(), default=self.started)
+        working = now - began
+        if progress <= 0 or working <= 0:
+            return None
+        return max(0.0, (self.total - progress) * working / progress)
+
+
+def clock(seconds: float | None) -> str:
+    """0:07, 3:41, 1:02:09."""
+    if seconds is None:
+        return "?"
+    s = int(round(seconds))
+    h, s = divmod(s, 3600)
+    m, s = divmod(s, 60)
+    return f"{h}:{m:02d}:{s:02d}" if h else f"{m}:{s:02d}"

modal_progress/watch.py

@@ -0,0 +1,169 @@
+"""Caller side: collect progress from the containers and draw it."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import threading
+import time
+from typing import Iterable, Iterator, TextIO
+
+from . import container
+from .render import PlainRenderer, RichRenderer
+from .state import State
+
+
+def pick_mode(mode: str | None = None, out: TextIO | None = None) -> str:
+    """rich in a terminal, plain lines anywhere else. MODAL_PROGRESS overrides."""
+    mode = mode or os.environ.get("MODAL_PROGRESS") or ""
+    if mode in ("rich", "plain", "off"):
+        return mode
+    stream = out or sys.stdout
+    return "rich" if getattr(stream, "isatty", lambda: False)() else "plain"
+
+
+class Watcher:
+    def __init__(
+        self,
+        app=None,
+        name: str = "map",
+        mode: str | None = None,
+        interval: float | None = None,
+        out: TextIO | None = None,
+        record: str | None = None,
+    ):
+        self.app = app
+        self.state = State(name=name)
+        self.lock = threading.Lock()
+        self.mode = pick_mode(mode, out)
+        interval = interval or float(os.environ.get("MODAL_PROGRESS_INTERVAL", 5))
+        if self.mode == "rich":
+            self.renderer = RichRenderer(self.state, self.lock)
+        elif self.mode == "plain":
+            self.renderer = PlainRenderer(self.state, self.lock, out=out, interval=interval)
+        else:
+            self.renderer = None
+        self._stop = threading.Event()
+        self._drain: threading.Thread | None = None
+        self._queue = None
+        self._key: str | None = None
+        self._record = open(record, "w", encoding="utf8") if record else None
+
+    def __enter__(self) -> "Watcher":
+        self.state.started = time.monotonic()
+        container.set_local_sink(self.feed)
+        key = getattr(self.app, "app_id", None) if self.app is not None else None
+        if key:
+            import modal
+
+            self._key = key
+            self._queue = modal.Queue.from_name(container.QUEUE_NAME, create_if_missing=True)
+            self._drain = threading.Thread(target=self._drain_loop, name="modal-progress-drain", daemon=True)
+            self._drain.start()
+        if self.renderer:
+            self.renderer.start()
+        return self
+
+    def __exit__(self, *exc) -> None:
+        container.set_local_sink(None)
+        if self._drain is not None:
+            self._stop.set()
+            self._drain.join(timeout=3)
+            try:
+                # Containers flush before returning, so the last events can still be queued.
+                for ev in self._queue.get_many(1024, block=False, partition=self._key):
+                    self.feed(ev)
+                self._queue.clear(partition=self._key)
+            except Exception:
+                pass
+        with self.lock:
+            self.state.finished = time.monotonic()
+        if self.renderer:
+            self.renderer.close()
+        if self._record:
+            self._write({"end": True, "done": self.state.done, "failed": self.state.failed})
+            self._record.close()
+
+    def _write(self, row: dict) -> None:
+        """One JSON line per event, timed from the start. Call with the lock held."""
+        if self._record:
+            row["at"] = round(time.monotonic() - self.state.started, 3)
+            row["wall"] = round(time.time(), 3)  # container clocks can differ from ours by seconds
+            self._record.write(json.dumps(row) + "\n")
+
+    def feed(self, ev: dict) -> None:
+        with self.lock:
+            self.state.apply(ev)
+            self._write({"ev": ev})
+
+    def _drain_loop(self) -> None:
+        while not self._stop.is_set():
+            try:
+                batch = self._queue.get_many(256, timeout=1.0, partition=self._key)
+            except Exception:
+                time.sleep(1.0)
+                continue
+            for ev in batch:
+                self.feed(ev)
+
+    def track(self, results: Iterable, total: int | None = None, name: str | None = None) -> Iterator:
+        """Passes results through and counts them. Exceptions count as failures.
+
+            for r in w.track(work.map(xs, return_exceptions=True), total=len(xs)):
+                ...
+        """
+        if total is None:
+            try:
+                total = len(results)  # type: ignore[arg-type]
+            except TypeError:
+                pass
+        with self.lock:
+            self.state.total = total
+            if name:
+                self.state.name = name
+            self._write({"start": True, "name": self.state.name, "total": total})
+        it = iter(results)
+        while True:
+            try:
+                r = next(it)
+            except StopIteration:
+                return
+            except Exception as e:
+                self._result(False, _describe(e))
+                raise
+            if isinstance(r, BaseException):
+                self._result(False, _describe(r))
+            else:
+                self._result(True)
+            yield r
+
+    def _result(self, ok: bool, error: str | None = None) -> None:
+        with self.lock:
+            self.state.result(ok, error)
+            self._write({"result": ok, "error": error})
+        if not ok and self.renderer:
+            self.renderer.failure(error or "")
+
+
+def _describe(e: BaseException) -> str:
+    text = str(e).strip().splitlines()
+    return f"{type(e).__name__}: {text[-1]}" if text else type(e).__name__
+
+
+def watch(
+    app=None,
+    name: str = "map",
+    mode: str | None = None,
+    interval: float | None = None,
+    out=None,
+    record: str | None = None,
+) -> Watcher:
+    """Shows live progress for a map while the block runs.
+
+        with watch(app, name="work") as w:
+            results = list(w.track(work.map(xs, return_exceptions=True)))
+
+    `record` writes every event to a JSON lines file, for replaying the run later.
+    """
+    return Watcher(app=app, name=name, mode=mode, interval=interval, out=out, record=record)

modal_progress-0.1.0.dist-info/METADATA

@@ -0,0 +1,128 @@
+Metadata-Version: 2.5
+Name: modal-progress
+Version: 0.1.0
+Summary: Live progress from inside Modal containers, for people at a terminal and agents reading a log
+Project-URL: Homepage, https://github.com/EnesYilmazcode/modal-progress
+Author: Enes Yilmaz
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: modal>=1.0
+Requires-Dist: rich>=13
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<h1 align="center">modal-progress</h1>
+
+<p align="center"><b>Live progress from inside Modal containers.</b><br>
+Progress bars per container in a terminal, plain progress lines in a log file.</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/EnesYilmazcode/modal-progress/main/assets/media/with-and-without.gif" width="820" alt="The same 60-input Modal job logged to a file: without modal-progress the log is silent until the end, with it there is a progress line every 5 seconds">
+</p>
+
+`modal run` draws `.map` progress as a live terminal bar. When the output goes to a file or a pipe, which is how coding agents run commands, nothing is printed until the job ends, so there is no way to tell a slow job from a stuck one. modal-progress prints a plain line every few seconds instead, and lets each container report its own progress.
+
+## Install
+
+```bash
+pip install git+https://github.com/EnesYilmazcode/modal-progress
+```
+
+Requires Python 3.10+ and modal 1.x.
+
+## Usage
+
+### No code changes
+
+Use `modal-progress run` in place of `modal run`. Arguments are passed through unchanged.
+
+```bash
+modal-progress run app.py > log.txt
+```
+
+```
+[progress] work 11/60 done (18%), 0:13 elapsed, eta 1:00
+[progress] work 19/60 done (32%), 0:20 elapsed, eta 0:44
+[progress] work 29/60 done (48%), 0:25 elapsed, eta 0:27
+[progress] work 60/60 done, 0:47
+```
+
+In a terminal it behaves exactly like `modal run`.
+
+### Progress from inside each container
+
+Wrap a loop in `bar()` inside the function, and wrap the map in `watch()` on the caller's side.
+
+```python
+import modal
+from modal_progress import bar, watch
+
+app = modal.App("example")
+image = modal.Image.debian_slim().add_local_python_source("modal_progress")
+
+@app.function(image=image)
+def work(i: int) -> int:
+    for step in bar(range(40), desc=f"input {i}"):
+        ...  # one step of work
+    return i
+
+@app.local_entrypoint()
+def main():
+    xs = range(60)
+    with watch(app, name="work") as w:
+        results = list(w.track(work.map(xs, return_exceptions=True), total=len(xs)))
+```
+
+In a terminal, this shows an overall bar plus one bar per container. In a log file, it prints:
+
+```
+[progress] work 20/60 done (33%), 0 failed, 6 running, 0:25 elapsed, eta 0:31
+[progress] work: an input failed: ValueError: bad input 37
+[progress] work 40/60 done (67%), 1 failed, 6 running, 0:40 elapsed, eta 0:14
+[progress] work finished: 60/60 done, 1 failed, 0:57
+```
+
+Failures are reported the moment they happen. Every line starts with `[progress]`, so it can be filtered with `grep`. A full example is in [`examples/fanout.py`](https://github.com/EnesYilmazcode/modal-progress/blob/main/examples/fanout.py).
+
+## API
+
+| Call | Where | What it does |
+|---|---|---|
+| `bar(iterable=None, total=None, desc="", every=0.5)` | container | tqdm-style wrapper. Also supports `update(n)`, `set_description(s)`, `close()`, and `with`. Sends at most one update every `every` seconds. |
+| `report(n, total=None, desc="")` | container | Sets progress for the current input directly, for loops `bar()` can't wrap. |
+| `watch(app, name="map", mode=None, interval=None, record=None)` | caller | Context manager that collects and draws progress. `record` writes every event to a JSON lines file. |
+| `w.track(results, total=None)` | caller | Passes map results through and counts them. Exceptions count as failures. |
+
+## Configuration
+
+| Variable | Values | Default |
+|---|---|---|
+| `MODAL_PROGRESS` | `rich`, `plain`, `off` | `rich` in a terminal, `plain` otherwise. `off` also stops containers from sending. |
+| `MODAL_PROGRESS_INTERVAL` | seconds between plain lines | `5` |
+
+## How it works
+
+Each container sends its latest progress to a [Modal Queue](https://modal.com/docs/reference/modal.Queue) named `modal-progress`, in a partition keyed by the app ID, batched every 0.25 seconds from a background thread. `watch()` reads that partition and combines it with the map's results as they come back. A `bar()` update costs about 0.2 µs, so it can wrap tight loops.
+
+`modal-progress run` needs no queue. It hooks Modal's own count of finished inputs and prints it as plain lines when stdout isn't a terminal.
+
+## Limitations
+
+- Uses three private Modal internals: `App._get_container_app()` to find the app ID in a container, Modal's live display to add the bars to it, and its map progress callback for `modal-progress run`. All are guarded, so if one changes you lose progress output, not the job. Tested on modal 1.6.1.
+- Works with `modal run` and `app.run()`. A deployed function called from a different app reports to its own app's partition, so the caller won't see it.
+- Progress shows up within about a second of happening.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+python -m pytest -q
+python -m modal_progress demo        # simulated map, no Modal account needed
+modal run examples/fanout.py         # real map on Modal
+```
+
+## License
+
+MIT

modal_progress-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+modal_progress/__init__.py,sha256=7aWWPQbZMAy6Y7ODzBVzCj36-gp4Oqvn0QecahkFwIg,191
+modal_progress/__main__.py,sha256=DLFH90R936iFjfUyB0KOA2jWeQZuTsh0_MB3Oh4aZ-Q,2169
+modal_progress/agent.py,sha256=tDxYagqerJ4Fp6G4etubKJBmz2eU4gUUbBfmbrZa20k,2895
+modal_progress/container.py,sha256=4mrXP2iV1AWcfHm7D-zk_BEYDrOb15QOy018dyPAQu8,6996
+modal_progress/render.py,sha256=d68VJPVY8RA6ChOCI30mOB2pAe9mfA34BuNCedr5Ix0,5976
+modal_progress/sim.py,sha256=6ixrSfIiX3jdIncUWU2rr2oIxQn6SJKiLyH_VWa8Imo,1615
+modal_progress/state.py,sha256=KySVHSkCsA3Fg8miOX_tPZW0JzXiqvS_KAG-jqIjHsU,3696
+modal_progress/watch.py,sha256=vhAYNkQRn5c2qSd1Fz18dM40dk1T-07zxa4wuJFTFDs,5955
+modal_progress-0.1.0.dist-info/METADATA,sha256=qHKv8G04tuPrHTd79Gz7IdkKSRa75xy34gjXRx_jdl0,5385
+modal_progress-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+modal_progress-0.1.0.dist-info/entry_points.txt,sha256=r_eaioXawBOcksEHOi6ld5wVd7aQG-CAb2HYToznSBw,64
+modal_progress-0.1.0.dist-info/licenses/LICENSE,sha256=l2BoUGp77thMwWpA0qNXlg1_3PEyxbFLV3Xx8wkxHpw,1068
+modal_progress-0.1.0.dist-info/RECORD,,

modal_progress-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

modal_progress-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+modal-progress = modal_progress.__main__:main

modal_progress-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Enes Yilmaz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.