@yahyahammad/venastine 0.1.0 → 0.2.0

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 ADDED
@@ -0,0 +1,268 @@
1
+ """
2
+ tui/meters.py
3
+
4
+ What a turn is costing, while it is being spent (batch 61).
5
+
6
+ THE PROBLEM IS SILENCE, and it is a silence this project built on purpose.
7
+ `markdown.commit_span` holds a table from its header row until a line that
8
+ is not a row arrives -- and a table, like an open ``` fence, is EXEMPT from
9
+ HOLD_LIMIT, the ceiling that bounds every other hold. So the gap between
10
+ "the model is writing a table" and "the table appears" has no upper bound.
11
+ Beside that, `tui/app.py` pauses the raven on every token delta, because a
12
+ redraw loop competing with deltas is the one place animation costs
13
+ responsiveness. Both decisions are right and they compose into one wrong
14
+ thing: the screen is most static exactly when the harness is busiest.
15
+
16
+ This module is the state behind three figures that move while that happens
17
+ -- elapsed, throughput, uptime -- and the fourth that lands in the
18
+ transcript when the turn ends, which is the part that says "done".
19
+
20
+ PURE. No I/O, no `core/` import, no harness state, and -- the one that is
21
+ easy to miss -- NO CLOCK. `tui/markdown.py`'s and `tui/diffs.py`'s rule with
22
+ one addition, because nothing in `tui/` or `core/` read a clock before this
23
+ batch and the first one to do it decides how every later one is tested.
24
+ Every method here takes `now` as a parameter. The clock lives in `app.py`,
25
+ which is the only file that has to know what a real second is; a test drives
26
+ this with the numbers it chooses and needs neither a Pilot nor a real timer.
27
+
28
+ WHAT THIS OWNS
29
+
30
+ - `start` / `stop` -- turn boundaries, and the elapsed time between.
31
+ - `set_blocked` -- the pause while a modal is waiting on a human.
32
+ - `add_output_chars` -- the live estimate's numerator.
33
+ - `subtitle` -- the three live figures as one string, or None.
34
+ - `completion` -- the line written under the finished answer.
35
+
36
+ TWO INSTRUMENTS, AND THEY ARE NOT THE SAME ONE. The live rate is an
37
+ ESTIMATE from characters, because `StreamToken` carries no incremental
38
+ usage and only three of the nineteen configured providers report usage on
39
+ a streaming call at all (D21: OpenAI-compatible streaming returns none
40
+ unless `stream_options` is sent, and Mistral rejects that parameter
41
+ outright). An exact live rate would therefore read `0 tok/s` forever on
42
+ sixteen providers, which is D21's own failure mode -- correct-looking
43
+ output -- one layer up in the UI. The estimate also keeps MOVING during a
44
+ table hold, because the deltas are still arriving; it is the renderer that
45
+ is withholding, not the stream. That is the whole point of the feature, so
46
+ the estimate is not a compromise here, it is the requirement.
47
+
48
+ The exact figure is the completion line's, from the provider's own count,
49
+ and it is marked with no tilde because it is not a guess. Where a provider
50
+ reports nothing the line says the time and MAKES NO TOKEN CLAIM -- it does
51
+ not print a zero, which is the difference between "we did not measure" and
52
+ "the model wrote nothing".
53
+ """
54
+
55
+ #: Characters per token, for the live estimate ONLY. A rough divisor
56
+ #: rather than a tokenizer: the exact count arrives at the end of the
57
+ #: turn from the provider, so anything spent being precise here would be
58
+ #: spent twice and still be wrong for whatever model is answering. The
59
+ #: tilde in front of the rendered figure is this constant, admitted.
60
+ CHARS_PER_TOKEN = 4
61
+
62
+ #: Below this many active seconds no rate is shown. A rate over a tenth of
63
+ #: a second is arithmetic on noise -- the first delta of a turn would
64
+ #: render four thousand tokens a second and then collapse, which reads as a
65
+ #: bug rather than as a measurement settling.
66
+ RATE_FLOOR_S = 0.5
67
+
68
+
69
+ def _duration(seconds: float) -> str:
70
+ """A turn's length, at a granularity that does not flicker.
71
+
72
+ Tenths under a minute, because that is the range a turn is usually in
73
+ and a whole-second figure looks stopped. Whole seconds above it, where
74
+ a tenth is noise the eye has to filter out on every redraw.
75
+ """
76
+ if seconds < 60:
77
+ return "%.1fs" % seconds
78
+ minutes, secs = divmod(int(seconds), 60)
79
+ if minutes < 60:
80
+ return "%dm%02ds" % (minutes, secs)
81
+ hours, minutes = divmod(minutes, 60)
82
+ return "%dh%02dm" % (hours, minutes)
83
+
84
+
85
+ def _uptime(seconds: float) -> str:
86
+ """How long this session has been on screen.
87
+
88
+ COARSER than `_duration` on purpose, and the reason is the change
89
+ guard in `app.py` rather than taste: a figure carrying tenths changes
90
+ on every tick, so it would repaint the border twice a second forever
91
+ to tell the reader something they are not watching. Minutes change a
92
+ minute apart, which is how often this is worth drawing.
93
+ """
94
+ if seconds < 60:
95
+ return "up %ds" % int(seconds)
96
+ minutes = int(seconds) // 60
97
+ if minutes < 60:
98
+ return "up %dm" % minutes
99
+ hours, minutes = divmod(minutes, 60)
100
+ return "up %dh%02dm" % (hours, minutes)
101
+
102
+
103
+ class TurnMeter:
104
+ """Elapsed, throughput and uptime for one shell session.
105
+
106
+ One object holds all three because they share a clock and a turn
107
+ boundary, and two objects agreeing about when a turn started is the
108
+ shape this project keeps removing.
109
+ """
110
+
111
+ def __init__(self):
112
+ # None until the session is on screen. `app.py` begins it in
113
+ # on_mount rather than __init__: "up" means the shell has been
114
+ # drawing, not that an object was constructed.
115
+ self._session_at = None
116
+ # None while idle. This IS the busy flag as far as this object is
117
+ # concerned, which is why `app.py` drives it from `_busy`'s setter
118
+ # -- one funnel, so a turn cannot start without starting a clock.
119
+ self._turn_at = None
120
+ # The modal pause, as a pair: when the current block began, and
121
+ # how much blocked time this turn has already accumulated.
122
+ self._blocked_at = None
123
+ self._blocked_total = 0.0
124
+ self._chars = 0
125
+
126
+ # -- session ------------------------------------------------------------
127
+
128
+ def begin_session(self, now: float) -> None:
129
+ """Idempotent: the first call wins.
130
+
131
+ A second call would restart uptime, and every caller that might
132
+ make one -- a remount, a screen push -- means "the session is
133
+ still going", not "a new one began".
134
+ """
135
+ if self._session_at is None:
136
+ self._session_at = now
137
+
138
+ # -- the turn -----------------------------------------------------------
139
+
140
+ @property
141
+ def running(self) -> bool:
142
+ return self._turn_at is not None
143
+
144
+ def start(self, now: float) -> None:
145
+ """Begin a turn. Idempotent, for `begin_session`'s reason: `_busy`
146
+ is assigned True at four sites and re-assigned inside at least one
147
+ of them, and the SECOND assignment must not reset the clock to
148
+ zero mid-turn."""
149
+ if self._turn_at is not None:
150
+ return
151
+ self._turn_at = now
152
+ self._blocked_at = None
153
+ self._blocked_total = 0.0
154
+ self._chars = 0
155
+
156
+ def stop(self, now: float):
157
+ """End a turn; the active seconds it took, or None if none was
158
+ running.
159
+
160
+ None rather than 0.0 is load-bearing: `_busy` is cleared on paths
161
+ where it was never set (a starter's early-return error branch runs
162
+ `self._busy = False` after its own `= True`, but `on_turn_finished`
163
+ can also arrive for a turn this object never saw), and a caller
164
+ must be able to tell "nothing was running" from "it took no time".
165
+ """
166
+ if self._turn_at is None:
167
+ return None
168
+ elapsed = self.elapsed(now)
169
+ self._turn_at = None
170
+ self._blocked_at = None
171
+ return elapsed
172
+
173
+ def set_blocked(self, blocked: bool, now: float) -> None:
174
+ """A modal is up (or is no longer up).
175
+
176
+ IDEMPOTENT, and that is what lets two routes drive it without
177
+ being two mechanisms. The tick reads `len(screen_stack) > 1` on
178
+ every refresh, which covers every modal including ones added
179
+ later; the permission path calls this directly, because with
180
+ `tui.animations: false` there is no tick to notice the
181
+ transition. Both land on one piece of state, so they cannot
182
+ disagree about whether the clock is paused -- only about how
183
+ promptly they noticed, and the earlier of the two wins.
184
+ """
185
+ if blocked:
186
+ if self._blocked_at is None:
187
+ self._blocked_at = now
188
+ return
189
+ if self._blocked_at is not None:
190
+ self._blocked_total += max(0.0, now - self._blocked_at)
191
+ self._blocked_at = None
192
+
193
+ def add_output_chars(self, count: int) -> None:
194
+ """Characters of answer received. The live rate's numerator.
195
+
196
+ Called per token delta, INCLUDING the ones being withheld by the
197
+ commit cap -- which is the point. The deltas arrive whether or not
198
+ the renderer is drawing them, so this is what keeps a figure
199
+ moving through a table hold.
200
+ """
201
+ if self._turn_at is not None:
202
+ self._chars += max(0, int(count or 0))
203
+
204
+ # -- reading it ---------------------------------------------------------
205
+
206
+ def elapsed(self, now: float) -> float:
207
+ """Active seconds in the current turn: wall clock minus the time a
208
+ modal spent waiting on a human.
209
+
210
+ Clamped at zero. `now` comes from a monotonic clock so it should
211
+ not go backwards, but a meter is not the thing that should raise
212
+ if it ever does.
213
+ """
214
+ if self._turn_at is None:
215
+ return 0.0
216
+ blocked = self._blocked_total
217
+ if self._blocked_at is not None:
218
+ blocked += max(0.0, now - self._blocked_at)
219
+ return max(0.0, (now - self._turn_at) - blocked)
220
+
221
+ def rate(self, now: float):
222
+ """Estimated tokens per second, or None when it would be noise."""
223
+ if self._turn_at is None or not self._chars:
224
+ return None
225
+ active = self.elapsed(now)
226
+ if active < RATE_FLOOR_S:
227
+ return None
228
+ return (self._chars / CHARS_PER_TOKEN) / active
229
+
230
+ def subtitle(self, now: float):
231
+ """The three live figures as one string, or None when there is
232
+ nothing to say yet.
233
+
234
+ None before the session has begun, so a bare-built app renders
235
+ the border it always rendered. Otherwise uptime is always there
236
+ -- it is the half that says the shell is alive when no turn is --
237
+ and the turn figures join it while one is running.
238
+ """
239
+ if self._session_at is None:
240
+ return None
241
+ parts = []
242
+ if self._turn_at is not None:
243
+ parts.append(_duration(self.elapsed(now)))
244
+ rate = self.rate(now)
245
+ if rate is not None:
246
+ parts.append("~%d tok/s" % round(rate))
247
+ parts.append(_uptime(max(0.0, now - self._session_at)))
248
+ return " ".join(parts)
249
+
250
+ def completion(self, elapsed: float, output_tokens=None) -> str:
251
+ """The line written under a finished answer.
252
+
253
+ `output_tokens` is the provider's own count for the turn, or None
254
+ where the provider reports none. NO TOKEN CLAIM is made in that
255
+ case -- not a zero, which would say the model wrote nothing on
256
+ sixteen of the nineteen configured providers.
257
+
258
+ The rate here carries no tilde. It is not the same instrument as
259
+ the live figure: that one divides characters by a constant, this
260
+ one divides the provider's count by the measured time.
261
+ """
262
+ text = "took %s" % _duration(elapsed)
263
+ if not output_tokens:
264
+ return text
265
+ text += " · %s tokens out" % format(int(output_tokens), ",")
266
+ if elapsed >= RATE_FLOOR_S:
267
+ text += " · %d tok/s" % round(output_tokens / elapsed)
268
+ return text