@yahyahammad/venastine 0.3.16 → 0.3.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/tui/meters.py CHANGED
@@ -30,9 +30,13 @@ WHAT THIS OWNS
30
30
  - `start` / `stop` -- turn boundaries, and the elapsed time between.
31
31
  - `set_blocked` -- the pause while a modal is waiting on a human.
32
32
  - `set_tool_running` -- the pause while a TOOL is running (rate only).
33
+ - `set_waiting` -- the pause while the turn waits on its
34
+ background sessions (rate only, §97 UF1).
33
35
  - `add_output_chars` -- the live estimate's numerator.
34
36
  - `subtitle` -- the three live figures as one string, or None.
35
37
  - `completion` -- the line written under the finished answer.
38
+ - `short_count` -- a token count as the usage line writes it,
39
+ in k, M or B (§97 UF3).
36
40
 
37
41
  TWO CLOCKS, AND THEY ANSWER DIFFERENT QUESTIONS (batch 118). `elapsed` is
38
42
  wall clock minus the human wait, because what it answers is "how long did I
@@ -40,6 +44,16 @@ wait for this turn", and a tool taking two minutes is part of that. The RATE
40
44
  divides by elapsed minus TOOL time, because what it answers is "how fast is
41
45
  the model writing", and a tool running is not the model writing.
42
46
 
47
+ THE COMPLETION LINE'S RATE TOO, AND THE SESSION WAIT (ROADMAP_v3 §97, UF1,
48
+ the owner's choice). Batch 118 moved only the live figure onto `generating`;
49
+ the line written under the answer kept dividing the provider's count by
50
+ `elapsed`. And a turn that starts background sessions is held open until
51
+ they finish (SS2), so its `elapsed` also held every second spent waiting on
52
+ them, between the wake turns that answer them. Both rates now divide by
53
+ `generating`, which leaves out the tools, the human wait and the session
54
+ wait; `took` stays `elapsed`, wall clock minus the human wait, because how
55
+ long the turn kept the shell is still that.
56
+
43
57
  Until batch 118 there was one clock and the rate used it, so the live figure
44
58
  read `~0 tok/s` on exactly the turns it exists for: it needs only fewer than
45
59
  two characters per active second to round to zero, and a turn that thinks for
@@ -81,6 +95,39 @@ CHARS_PER_TOKEN = 4
81
95
  RATE_FLOOR_S = 0.5
82
96
 
83
97
 
98
+ #: The units `short_count` steps through, smallest first.
99
+ _COUNT_UNITS = ((1_000, "k"), (1_000_000, "M"), (1_000_000_000, "B"))
100
+
101
+
102
+ def short_count(n) -> str:
103
+ """A token count in a few columns: `950`, `118k`, `1.2M`, `12M`, `1.5B`
104
+ (ROADMAP_v3 §97, UF3, the owner's choice).
105
+
106
+ THE ONE FORMATTER FOR THE USAGE LINE. Its `ctx`, window, fold point and
107
+ `billed` were each written in whole thousands, so a thread past a
108
+ million billed read `billed 12345k`, which is a number the eye has to
109
+ count digits in. One decimal below ten of a unit, where a whole number
110
+ would hide the difference between 1.2M and 1.9M; whole units above.
111
+
112
+ A figure that ROUNDS UP to a thousand of its unit is written in the
113
+ next one -- 999,600 is `1.0M`, never `1000k` -- and B is the last unit.
114
+ Thousands are written as before (`.0f`), so a line that read `118k`
115
+ still does. Not for a figure the user typed and is reading back:
116
+ `/window` and `/trigger` echo theirs exactly, by the owner's choice.
117
+ """
118
+ n = max(0, int(n or 0))
119
+ if n < 1000:
120
+ return str(n)
121
+ for index, (size, unit) in enumerate(_COUNT_UNITS):
122
+ value = n / size
123
+ whole = unit == "k" or value >= 9.95
124
+ text = "%.0f" % value if whole else "%.1f" % value
125
+ if float(text) >= 1000 and index < len(_COUNT_UNITS) - 1:
126
+ continue
127
+ return text + unit
128
+ return str(n) # unreachable: the last unit always returns
129
+
130
+
84
131
  def _duration(seconds: float) -> str:
85
132
  """A turn's length, at a granularity that does not flicker.
86
133
 
@@ -136,13 +183,17 @@ class TurnMeter:
136
183
  # how much blocked time this turn has already accumulated.
137
184
  self._blocked_at = None
138
185
  self._blocked_total = 0.0
139
- # The tool pause, same shape as the modal one, plus a DEPTH --
140
- # `_dispatch_parallel` can have several tools outstanding at once,
141
- # so a boolean would un-pause on the first result while two were
142
- # still running.
143
- self._tool_at = None
144
- self._tool_total = 0.0
186
+ # The RATE's pause, same shape as the modal one: open while a tool
187
+ # runs or the turn waits on its background sessions (§97 UF1), and
188
+ # never while a modal is up -- see set_blocked. ONE window for both,
189
+ # because neither is the model writing and the rate never needs to
190
+ # tell them apart. The tools are a DEPTH -- `_dispatch_parallel`
191
+ # can have several outstanding at once, so a boolean would un-pause
192
+ # on the first result while two were still running.
193
+ self._paused_at = None
194
+ self._paused_total = 0.0
145
195
  self._tool_depth = 0
196
+ self._waiting = False
146
197
  self._chars = 0
147
198
 
148
199
  # -- session ------------------------------------------------------------
@@ -173,9 +224,10 @@ class TurnMeter:
173
224
  self._turn_at = now
174
225
  self._blocked_at = None
175
226
  self._blocked_total = 0.0
176
- self._tool_at = None
177
- self._tool_total = 0.0
227
+ self._paused_at = None
228
+ self._paused_total = 0.0
178
229
  self._tool_depth = 0
230
+ self._waiting = False
179
231
  self._chars = 0
180
232
 
181
233
  def stop(self, now: float):
@@ -193,8 +245,9 @@ class TurnMeter:
193
245
  elapsed = self.elapsed(now)
194
246
  self._turn_at = None
195
247
  self._blocked_at = None
196
- self._tool_at = None
248
+ self._paused_at = None
197
249
  self._tool_depth = 0
250
+ self._waiting = False
198
251
  return elapsed
199
252
 
200
253
  def set_blocked(self, blocked: bool, now: float) -> None:
@@ -216,17 +269,17 @@ class TurnMeter:
216
269
  # that keeps them apart. Approval is asked for from inside
217
270
  # a tool call, so a human wait sits inside a tool window;
218
271
  # `elapsed` already removes the human wait, so letting the
219
- # tool clock keep running across it would subtract the same
220
- # seconds twice and could drive the rate's denominator
221
- # negative. The tool clock is closed here and reopened when
222
- # the modal goes away, which is `set_blocked(False)` below.
223
- self._close_tool_window(now)
272
+ # rate's pause keep running across it would subtract the
273
+ # same seconds twice and could drive the rate's denominator
274
+ # negative. The pause is closed here and reopened when the
275
+ # modal goes away, which is `set_blocked(False)` below. A
276
+ # modal opened during the session wait is the same case.
277
+ self._sync_pause(now)
224
278
  return
225
279
  if self._blocked_at is not None:
226
280
  self._blocked_total += max(0.0, now - self._blocked_at)
227
281
  self._blocked_at = None
228
- if self._tool_depth > 0:
229
- self._tool_at = now
282
+ self._sync_pause(now)
230
283
 
231
284
  def set_tool_running(self, delta: int, now: float) -> None:
232
285
  """A tool started (+1) or finished (-1).
@@ -243,20 +296,41 @@ class TurnMeter:
243
296
  """
244
297
  if self._turn_at is None:
245
298
  return
246
- previous = self._tool_depth
247
- self._tool_depth = max(0, previous + int(delta))
248
- if self._tool_depth and previous == 0:
249
- # Not while a modal is up: see set_blocked.
250
- if self._blocked_at is None:
251
- self._tool_at = now
252
- elif not self._tool_depth and previous:
253
- self._close_tool_window(now)
299
+ self._tool_depth = max(0, self._tool_depth + int(delta))
300
+ self._sync_pause(now)
301
+
302
+ def set_waiting(self, waiting: bool, now: float) -> None:
303
+ """The turn is (or is no longer) waiting on its background sessions
304
+ (ROADMAP_v3 §97, UF1).
305
+
306
+ `tui/app.py`'s `_wait_for_sessions` holds a turn open after its
307
+ answer until the sessions it started are done (SS2), and runs a
308
+ wake turn for each batch of their results. The seconds BETWEEN wake
309
+ turns are the shell waiting, not the model writing, so the rate
310
+ leaves them out; `elapsed` keeps them, as it keeps a tool's, since
311
+ the turn did keep the shell that long. Idempotent, like every
312
+ setter here.
313
+ """
314
+ if self._turn_at is None:
315
+ return
316
+ self._waiting = bool(waiting)
317
+ self._sync_pause(now)
254
318
 
255
- def _close_tool_window(self, now: float) -> None:
256
- """Bank an open tool window, if there is one. Idempotent."""
257
- if self._tool_at is not None:
258
- self._tool_total += max(0.0, now - self._tool_at)
259
- self._tool_at = None
319
+ def _sync_pause(self, now: float) -> None:
320
+ """Open or bank the rate's pause to match what is happening.
321
+
322
+ Open while a tool runs or the turn waits on its sessions, and never
323
+ while a modal is up (`set_blocked` keeps the two disjoint).
324
+ Idempotent: a second tool starting inside an open window, or a
325
+ second `set_waiting(True)`, leaves the window where it began.
326
+ """
327
+ paused = ((self._tool_depth > 0 or self._waiting)
328
+ and self._blocked_at is None)
329
+ if paused and self._paused_at is None:
330
+ self._paused_at = now
331
+ elif not paused and self._paused_at is not None:
332
+ self._paused_total += max(0.0, now - self._paused_at)
333
+ self._paused_at = None
260
334
 
261
335
  def add_output_chars(self, count: int) -> None:
262
336
  """Characters the MODEL GENERATED. The live rate's numerator.
@@ -296,11 +370,13 @@ class TurnMeter:
296
370
  return max(0.0, (now - self._turn_at) - blocked)
297
371
 
298
372
  def generating(self, now: float) -> float:
299
- """Active seconds with a tool NOT running: the rate's denominator.
373
+ """Active seconds with no tool running and no session wait: the
374
+ rate's denominator, live and on the completion line (§97 UF1).
300
375
 
301
- `elapsed` minus tool time. See the module docstring for why these
302
- are two numbers rather than one -- briefly, a tool running is part
303
- of how long the turn took and no part of how fast the model writes.
376
+ `elapsed` minus the rate's pause. See the module docstring for why
377
+ these are two numbers rather than one -- briefly, a tool running is
378
+ part of how long the turn took and no part of how fast the model
379
+ writes, and so is waiting on a background session.
304
380
 
305
381
  Clamped, and the clamp is doing real work rather than being
306
382
  defensive: the two pauses are kept disjoint by `set_blocked`, and
@@ -309,10 +385,10 @@ class TurnMeter:
309
385
  """
310
386
  if self._turn_at is None:
311
387
  return 0.0
312
- tool = self._tool_total
313
- if self._tool_at is not None:
314
- tool += max(0.0, now - self._tool_at)
315
- return max(0.0, self.elapsed(now) - tool)
388
+ paused = self._paused_total
389
+ if self._paused_at is not None:
390
+ paused += max(0.0, now - self._paused_at)
391
+ return max(0.0, self.elapsed(now) - paused)
316
392
 
317
393
  def rate(self, now: float):
318
394
  """Estimated tokens per second, or None when it would be noise."""
@@ -343,7 +419,8 @@ class TurnMeter:
343
419
  parts.append(_uptime(max(0.0, now - self._session_at)))
344
420
  return " ".join(parts)
345
421
 
346
- def completion(self, elapsed: float, output_tokens=None) -> str:
422
+ def completion(self, elapsed: float, output_tokens=None,
423
+ generating=None) -> str:
347
424
  """The line written under a finished answer.
348
425
 
349
426
  `output_tokens` is the provider's own count for the turn, or None
@@ -354,11 +431,18 @@ class TurnMeter:
354
431
  The rate here carries no tilde. It is not the same instrument as
355
432
  the live figure: that one divides characters by a constant, this
356
433
  one divides the provider's count by the measured time.
434
+
435
+ THE MEASURED TIME IS `generating` (ROADMAP_v3 §97, UF1), the
436
+ turn's seconds with no tool running and no session wait, which the
437
+ caller reads off `generating()` before it stops the turn. `took`
438
+ is still `elapsed`. A caller that passes no `generating` gets the
439
+ old division, since that is the only time it has.
357
440
  """
358
441
  text = "took %s" % _duration(elapsed)
359
442
  if not output_tokens:
360
443
  return text
361
444
  text += " · %s tokens out" % format(int(output_tokens), ",")
362
- if elapsed >= RATE_FLOOR_S:
363
- text += " · %d tok/s" % round(output_tokens / elapsed)
445
+ seconds = elapsed if generating is None else generating
446
+ if seconds >= RATE_FLOOR_S:
447
+ text += " · %d tok/s" % round(output_tokens / seconds)
364
448
  return text
package/tui/widgets.py CHANGED
@@ -39,6 +39,7 @@ from core.ansi import AnsiStripper
39
39
  from prompts.system_prompts import pass_label
40
40
  from tui import diffs, markdown, ravens, themes
41
41
  from tui.commands import registry as commands
42
+ from tui.meters import short_count
42
43
 
43
44
 
44
45
  def as_content(text: Text) -> Content:
@@ -537,29 +538,29 @@ class UsageLine(Static):
537
538
  return
538
539
  self._last = key
539
540
 
540
- def _k(n: int) -> str:
541
- return f"{n / 1000:.0f}k" if n >= 1000 else str(n)
542
-
543
541
  self.display = True
544
542
  mark = "*" if overridden else ""
545
543
  if window:
546
544
  # The limit as the scale, the fold point named as what it is.
547
- scale = f"/{_k(window)}"
548
- scale += f" (fold {_k(ceiling)}{mark})" if ceiling else ""
545
+ scale = f"/{short_count(window)}"
546
+ scale += f" (fold {short_count(ceiling)}{mark})" if ceiling else ""
549
547
  elif ceiling:
550
548
  # No window resolved -- context_limit() always answers, so this
551
549
  # is the bare-built widget and the pre-batch-119 callers that
552
550
  # pass four arguments. The old shape exactly, rather than a
553
551
  # blank scale, because a trigger is still better than nothing.
554
- scale = f"/{_k(ceiling)}{mark}"
552
+ scale = f"/{short_count(ceiling)}{mark}"
555
553
  else:
556
554
  scale = ""
557
555
  # `system` is the harness-talking-about-itself role -- the right
558
556
  # meaning for a usage line, and the palette route the batch-26
559
557
  # guard test demands (it caught this line as a literal within one
560
558
  # commit of the widget existing).
559
+ # ROADMAP_v3 §97 (UF3): every figure here through the one k/M/B
560
+ # formatter, so `billed` past a million reads `1.2M`, not `1200k`.
561
561
  self.update(as_content(
562
- Text(f"usage · ctx {_k(ctx)}{scale} · billed {_k(billed)}",
562
+ Text(f"usage · ctx {short_count(ctx)}{scale} · "
563
+ f"billed {short_count(billed)}",
563
564
  style=self._styles().get("system", ""))))
564
565
 
565
566