nullius-eval 0.1.0__py3-none-any.whl

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.
Files changed (291) hide show
  1. _nullius_app/.env.example +55 -0
  2. _nullius_app/app.py +96 -0
  3. _nullius_app/requirements.txt +1 -0
  4. _nullius_app/static/brand/README.md +20 -0
  5. _nullius_app/static/brand/docker.svg +1 -0
  6. _nullius_app/static/brand/favicon.svg +1 -0
  7. _nullius_app/static/brand/huggingface.svg +37 -0
  8. _nullius_app/static/brand/mark-dark.svg +1 -0
  9. _nullius_app/static/brand/marks.svg +34 -0
  10. _nullius_app/static/brand/tokens.json +51 -0
  11. _nullius_app/static/brand/typesafe.png +0 -0
  12. _nullius_app/static/brand/wordmark-dark.svg +1 -0
  13. _nullius_app/static/builder/command-builder-core.js +763 -0
  14. _nullius_app/static/builder/command-builder.css +248 -0
  15. _nullius_app/static/builder/command-builder.js +997 -0
  16. _nullius_app/static/builder/model-picker.js +113 -0
  17. _nullius_app/static/catalogue/add.js +46 -0
  18. _nullius_app/static/catalogue/agents/README.md +19 -0
  19. _nullius_app/static/catalogue/agents/goose.svg +1 -0
  20. _nullius_app/static/catalogue/agents/jiuwenswarm.svg +33 -0
  21. _nullius_app/static/catalogue/agents/marks.json +8 -0
  22. _nullius_app/static/catalogue/agents/mini-swe-agent.svg +7 -0
  23. _nullius_app/static/catalogue/agents/opencode.svg +7 -0
  24. _nullius_app/static/catalogue/catalogue.css +436 -0
  25. _nullius_app/static/catalogue/catalogue.js +87 -0
  26. _nullius_app/static/catalogue/marks.svg +29 -0
  27. _nullius_app/static/catalogue/new.js +78 -0
  28. _nullius_app/static/catalogue/versions.js +27 -0
  29. _nullius_app/static/compare/comparison.css +117 -0
  30. _nullius_app/static/controls.js +117 -0
  31. _nullius_app/static/disclosures.js +70 -0
  32. _nullius_app/static/fonts/0569c822cab6c510.ttf +0 -0
  33. _nullius_app/static/fonts/DMSans-Medium.woff2 +0 -0
  34. _nullius_app/static/fonts/DMSans-Regular.woff2 +0 -0
  35. _nullius_app/static/fonts/IBMPlexMono-Medium.woff2 +0 -0
  36. _nullius_app/static/fonts/IBMPlexMono-Regular.woff2 +0 -0
  37. _nullius_app/static/fonts/InstrumentSerif-Italic.woff2 +0 -0
  38. _nullius_app/static/fonts/InstrumentSerif-Regular.woff2 +0 -0
  39. _nullius_app/static/fonts/README.md +11 -0
  40. _nullius_app/static/fonts/c1e7453ea26a1d1e.ttf +0 -0
  41. _nullius_app/static/fonts/dmsans-OFL.txt +93 -0
  42. _nullius_app/static/fonts/ibmplexmono-OFL.txt +93 -0
  43. _nullius_app/static/fonts/instrumentserif-OFL.txt +93 -0
  44. _nullius_app/static/fonts.css +49 -0
  45. _nullius_app/static/notifications.js +49 -0
  46. _nullius_app/static/onboarding.css +78 -0
  47. _nullius_app/static/onboarding.js +158 -0
  48. _nullius_app/static/runs/board.css +358 -0
  49. _nullius_app/static/runs/board.js +127 -0
  50. _nullius_app/static/runs/launches.css +88 -0
  51. _nullius_app/static/runs/live-board.css +186 -0
  52. _nullius_app/static/runs/live-board.js +394 -0
  53. _nullius_app/static/runs/path-suggestions.js +119 -0
  54. _nullius_app/static/runs/start.css +38 -0
  55. _nullius_app/static/settings/autosave.js +162 -0
  56. _nullius_app/static/settings/custom-keys.js +100 -0
  57. _nullius_app/static/settings/data-providers.js +88 -0
  58. _nullius_app/static/settings/judges.js +61 -0
  59. _nullius_app/static/settings/modal.css +32 -0
  60. _nullius_app/static/settings/modal.js +91 -0
  61. _nullius_app/static/settings/navigation.js +55 -0
  62. _nullius_app/static/settings/prices.js +68 -0
  63. _nullius_app/static/settings/providers.js +134 -0
  64. _nullius_app/static/settings/sandbox.js +20 -0
  65. _nullius_app/static/settings/settings.css +288 -0
  66. _nullius_app/static/style.css +1752 -0
  67. _nullius_app/static/traces/conversation.css +49 -0
  68. _nullius_app/static/traces/conversation.js +215 -0
  69. _nullius_app/templates/agents/entry.html +145 -0
  70. _nullius_app/templates/agents/kits.html +55 -0
  71. _nullius_app/templates/agents/standard.html +58 -0
  72. _nullius_app/templates/base.html +479 -0
  73. _nullius_app/templates/builder/new_run.html +55 -0
  74. _nullius_app/templates/catalogue/add_dialog.html +32 -0
  75. _nullius_app/templates/catalogue/benchmark.html +270 -0
  76. _nullius_app/templates/catalogue/benchmarks.html +91 -0
  77. _nullius_app/templates/catalogue/new.html +141 -0
  78. _nullius_app/templates/catalogue/use_bundle.html +11 -0
  79. _nullius_app/templates/compare/_detail.html +37 -0
  80. _nullius_app/templates/compare/compare.html +298 -0
  81. _nullius_app/templates/compare/compare_picker.html +51 -0
  82. _nullius_app/templates/compare/compare_task.html +329 -0
  83. _nullius_app/templates/runs/_execution.html +131 -0
  84. _nullius_app/templates/runs/_runtime.html +5 -0
  85. _nullius_app/templates/runs/ascii-mark.html +485 -0
  86. _nullius_app/templates/runs/feasibility.html +127 -0
  87. _nullius_app/templates/runs/index.html +609 -0
  88. _nullius_app/templates/runs/job.html +460 -0
  89. _nullius_app/templates/runs/preparing.html +14 -0
  90. _nullius_app/templates/runs/reconcile.html +124 -0
  91. _nullius_app/templates/runs/setup.html +272 -0
  92. _nullius_app/templates/runs/start.html +51 -0
  93. _nullius_app/templates/settings/custom_keys.html +82 -0
  94. _nullius_app/templates/settings/data_providers.html +27 -0
  95. _nullius_app/templates/settings/settings.html +564 -0
  96. _nullius_app/templates/traces/_charts.html +165 -0
  97. _nullius_app/templates/traces/_conversation.html +37 -0
  98. _nullius_app/templates/traces/_judgement.html +72 -0
  99. _nullius_app/templates/traces/artifact.html +15 -0
  100. _nullius_app/templates/traces/trial.html +838 -0
  101. _nullius_app/templates/workspaces/workspaces.html +54 -0
  102. _nullius_app/web/__init__.py +1 -0
  103. _nullius_app/web/agents.py +230 -0
  104. _nullius_app/web/builder.py +406 -0
  105. _nullius_app/web/catalogue.py +370 -0
  106. _nullius_app/web/compare.py +489 -0
  107. _nullius_app/web/core.py +17 -0
  108. _nullius_app/web/execute.py +223 -0
  109. _nullius_app/web/feasibility.py +60 -0
  110. _nullius_app/web/filters.py +231 -0
  111. _nullius_app/web/judge.py +623 -0
  112. _nullius_app/web/judge_tasks.py +33 -0
  113. _nullius_app/web/onboarding.py +20 -0
  114. _nullius_app/web/reconcile.py +47 -0
  115. _nullius_app/web/runs.py +464 -0
  116. _nullius_app/web/settings.py +324 -0
  117. _nullius_app/web/shared.py +507 -0
  118. _nullius_app/web/traces.py +306 -0
  119. _nullius_app/web/workspaces.py +84 -0
  120. nullius/__init__.py +32 -0
  121. nullius/__main__.py +5 -0
  122. nullius/catalogue/__init__.py +0 -0
  123. nullius/catalogue/agents/codex/agent.json +222 -0
  124. nullius/catalogue/agents/codex/config.toml +25 -0
  125. nullius/catalogue/agents/goose/agent.json +131 -0
  126. nullius/catalogue/agents/goose/config.yaml +20 -0
  127. nullius/catalogue/agents/jiuwenswarm/agent.json +197 -0
  128. nullius/catalogue/agents/jiuwenswarm/agent.py +355 -0
  129. nullius/catalogue/agents/mini-swe-agent/agent.json +68 -0
  130. nullius/catalogue/agents/mini-swe-agent/run.py +37 -0
  131. nullius/catalogue/agents/opencode/agent.json +135 -0
  132. nullius/catalogue/agents/opencode/opencode.json +32 -0
  133. nullius/catalogue/agents/reference/agent.json +89 -0
  134. nullius/catalogue/agents/reference/agent.py +209 -0
  135. nullius/catalogue/agents/terminus-2/agent.json +64 -0
  136. nullius/catalogue/agents/terminus-2/run.py +139 -0
  137. nullius/catalogue/benchmarks/gaia/benchmark.json +72 -0
  138. nullius/catalogue/benchmarks/gaia/data-source.json +29 -0
  139. nullius/catalogue/benchmarks/gaia/driver.py +188 -0
  140. nullius/catalogue/benchmarks/gaia/env/data.Dockerfile +1 -0
  141. nullius/catalogue/benchmarks/gaia/standard.json +278 -0
  142. nullius/catalogue/benchmarks/gaia/upstream-settings.json +275 -0
  143. nullius/catalogue/benchmarks/gsm8k/benchmark.json +34 -0
  144. nullius/catalogue/benchmarks/gsm8k/driver.py +101 -0
  145. nullius/catalogue/benchmarks/gsm8k/standard.json +124 -0
  146. nullius/catalogue/benchmarks/gsm8k/upstream-settings.json +86 -0
  147. nullius/catalogue/benchmarks/humaneval/benchmark.json +36 -0
  148. nullius/catalogue/benchmarks/humaneval/driver.py +243 -0
  149. nullius/catalogue/benchmarks/humaneval/standard.json +115 -0
  150. nullius/catalogue/benchmarks/humaneval/upstream-settings.json +72 -0
  151. nullius/catalogue/benchmarks/locomo/benchmark.json +43 -0
  152. nullius/catalogue/benchmarks/locomo/driver.py +270 -0
  153. nullius/catalogue/benchmarks/locomo/standard.json +265 -0
  154. nullius/catalogue/benchmarks/locomo/upstream-settings.json +112 -0
  155. nullius/catalogue/benchmarks/longmemeval/benchmark.json +65 -0
  156. nullius/catalogue/benchmarks/longmemeval/driver.py +379 -0
  157. nullius/catalogue/benchmarks/longmemeval/standard.json +733 -0
  158. nullius/catalogue/benchmarks/longmemeval/upstream-settings.json +76 -0
  159. nullius/catalogue/benchmarks/swe-bench-verified/benchmark.json +87 -0
  160. nullius/catalogue/benchmarks/swe-bench-verified/driver.py +116 -0
  161. nullius/catalogue/benchmarks/swe-bench-verified/images.json +502 -0
  162. nullius/catalogue/benchmarks/swe-bench-verified/standard.json +108 -0
  163. nullius/catalogue/benchmarks/swe-bench-verified/upstream-settings.json +32 -0
  164. nullius/catalogue/benchmarks/tau3-bench/benchmark.json +49 -0
  165. nullius/catalogue/benchmarks/tau3-bench/driver.py +608 -0
  166. nullius/catalogue/benchmarks/tau3-bench/mcp_server.py +114 -0
  167. nullius/catalogue/benchmarks/tau3-bench/search_relay.py +19 -0
  168. nullius/catalogue/benchmarks/tau3-bench/standard.json +547 -0
  169. nullius/catalogue/benchmarks/tau3-bench/upstream-settings.json +639 -0
  170. nullius/catalogue/benchmarks/terminal-bench/benchmark.json +69 -0
  171. nullius/catalogue/benchmarks/terminal-bench/driver.py +267 -0
  172. nullius/catalogue/benchmarks/terminal-bench/standard.json +166 -0
  173. nullius/catalogue/benchmarks/terminal-bench/upstream-settings.json +36 -0
  174. nullius/catalogue/capabilities/keyword-memory/capability.json +33 -0
  175. nullius/catalogue/capabilities/keyword-memory/capability.py +55 -0
  176. nullius/catalogue/capabilities/mem0/capability.json +135 -0
  177. nullius/catalogue/capabilities/mem0/capability.py +173 -0
  178. nullius/catalogue/catalog.py +426 -0
  179. nullius/catalogue/citation.py +116 -0
  180. nullius/catalogue/harbor_entry.py +367 -0
  181. nullius/catalogue/sources.py +107 -0
  182. nullius/catalogue/storage.py +125 -0
  183. nullius/cli.py +85 -0
  184. nullius/compare/__init__.py +0 -0
  185. nullius/compare/cli.py +265 -0
  186. nullius/compare/comparison.py +184 -0
  187. nullius/execution.py +1653 -0
  188. nullius/gitrefs.py +128 -0
  189. nullius/harbor/__init__.py +0 -0
  190. nullius/harbor/feed.py +228 -0
  191. nullius/harbor/source.py +582 -0
  192. nullius/hosts.py +368 -0
  193. nullius/importers/__init__.py +140 -0
  194. nullius/importers/atif.py +387 -0
  195. nullius/importers/cli.py +135 -0
  196. nullius/importers/otel.py +274 -0
  197. nullius/judge/__init__.py +14 -0
  198. nullius/judge/batch.py +122 -0
  199. nullius/judge/client.py +433 -0
  200. nullius/judge/floors.json +86 -0
  201. nullius/judge/lanes.py +89 -0
  202. nullius/judge/questions.py +309 -0
  203. nullius/judge/reconcile.py +176 -0
  204. nullius/judge/state.py +224 -0
  205. nullius/judge/store.py +167 -0
  206. nullius/migrate.py +268 -0
  207. nullius/onboarding.py +116 -0
  208. nullius/paths.py +89 -0
  209. nullius/prerequisites.py +129 -0
  210. nullius/prices.py +283 -0
  211. nullius/progress.py +294 -0
  212. nullius/providers.py +335 -0
  213. nullius/recipes/__init__.py +0 -0
  214. nullius/recipes/launch.py +78 -0
  215. nullius/redact.py +72 -0
  216. nullius/runs/__init__.py +0 -0
  217. nullius/runs/artifacts.py +67 -0
  218. nullius/runs/classify.py +216 -0
  219. nullius/runs/cli.py +316 -0
  220. nullius/runs/feasibility.py +442 -0
  221. nullius/runs/launches.py +149 -0
  222. nullius/runs/live.py +715 -0
  223. nullius/runs/parse.py +1016 -0
  224. nullius/runs/verifier.py +241 -0
  225. nullius/sandbox.py +109 -0
  226. nullius/secrets.py +218 -0
  227. nullius/settings.py +544 -0
  228. nullius/standard/__init__.py +15 -0
  229. nullius/standard/acp.py +305 -0
  230. nullius/standard/cancellation.py +19 -0
  231. nullius/standard/cli.py +703 -0
  232. nullius/standard/conform.py +149 -0
  233. nullius/standard/container.py +1870 -0
  234. nullius/standard/definitions.py +1651 -0
  235. nullius/standard/egress.py +192 -0
  236. nullius/standard/fidelity.py +256 -0
  237. nullius/standard/forward.py +139 -0
  238. nullius/standard/hostreq.py +105 -0
  239. nullius/standard/howto.py +220 -0
  240. nullius/standard/install.py +428 -0
  241. nullius/standard/job.py +551 -0
  242. nullius/standard/jsonl.py +129 -0
  243. nullius/standard/kits/agent-conversation-v1/driver.py +27 -0
  244. nullius/standard/kits/agent-conversation-v1/standard.json +26 -0
  245. nullius/standard/kits/agent-search-v1/driver.py +171 -0
  246. nullius/standard/kits/agent-search-v1/standard.json +99 -0
  247. nullius/standard/kits/agent-task-v1/driver.py +25 -0
  248. nullius/standard/kits/agent-task-v1/standard.json +100 -0
  249. nullius/standard/kits/agent-tools-v1/driver.py +206 -0
  250. nullius/standard/kits/agent-tools-v1/mcp_kit.py +209 -0
  251. nullius/standard/kits/agent-tools-v1/standard.json +119 -0
  252. nullius/standard/kits/agent-workspace-v1/driver.py +65 -0
  253. nullius/standard/kits/agent-workspace-v1/standard.json +95 -0
  254. nullius/standard/kits/cap-memory-v1/driver.py +39 -0
  255. nullius/standard/kits/cap-memory-v1/standard.json +91 -0
  256. nullius/standard/ledger.py +326 -0
  257. nullius/standard/match.py +66 -0
  258. nullius/standard/mcp_bridge.py +62 -0
  259. nullius/standard/mcp_machine.py +193 -0
  260. nullius/standard/merge.py +239 -0
  261. nullius/standard/names.py +37 -0
  262. nullius/standard/network_requirements.py +44 -0
  263. nullius/standard/pace.py +53 -0
  264. nullius/standard/payload.py +278 -0
  265. nullius/standard/pins.py +130 -0
  266. nullius/standard/ports.py +70 -0
  267. nullius/standard/prove.py +373 -0
  268. nullius/standard/recipe.py +746 -0
  269. nullius/standard/relay.py +785 -0
  270. nullius/standard/run.py +1781 -0
  271. nullius/standard/setup_container.py +208 -0
  272. nullius/standard/shard.py +71 -0
  273. nullius/standard/web_services.py +30 -0
  274. nullius/traces/__init__.py +0 -0
  275. nullius/traces/behavior.py +131 -0
  276. nullius/traces/charts.py +898 -0
  277. nullius/traces/conversation.py +159 -0
  278. nullius/traces/otel.py +608 -0
  279. nullius/traces/trace.py +1477 -0
  280. nullius/traces/trajectory.py +586 -0
  281. nullius/workspace.py +417 -0
  282. nullius/workspace_cli.py +119 -0
  283. nullius_eval-0.1.0.dist-info/METADATA +93 -0
  284. nullius_eval-0.1.0.dist-info/RECORD +291 -0
  285. nullius_eval-0.1.0.dist-info/WHEEL +5 -0
  286. nullius_eval-0.1.0.dist-info/entry_points.txt +2 -0
  287. nullius_eval-0.1.0.dist-info/licenses/LICENSE +202 -0
  288. nullius_eval-0.1.0.dist-info/licenses/app/static/fonts/dmsans-OFL.txt +93 -0
  289. nullius_eval-0.1.0.dist-info/licenses/app/static/fonts/ibmplexmono-OFL.txt +93 -0
  290. nullius_eval-0.1.0.dist-info/licenses/app/static/fonts/instrumentserif-OFL.txt +93 -0
  291. nullius_eval-0.1.0.dist-info/top_level.txt +2 -0
@@ -0,0 +1,898 @@
1
+ """Distribution charts over a trace's spans: histograms and CDFs.
2
+
3
+ A sibling to the waterfall, answering a different question. The waterfall and the
4
+ breakdown strips are *timeline* views — when things happened, and how the wall
5
+ clock splits. This module describes the *population* of calls: how long a typical
6
+ tool call runs, whether the LLM calls are bimodal, whether a handful of spans
7
+ hold most of the time.
8
+
9
+ **Summed span duration is not wall clock, and nothing here may imply it is.**
10
+ Spans nest and overlap — a tool call sits inside the LLM call that asked for it,
11
+ and background subagents run alongside the main thread — so adding durations up
12
+ overshoots the run, sometimes by a lot. That is exactly why the strips next to
13
+ these charts never sum spans: ``Totals`` is the producer's, displayed verbatim,
14
+ and ``Breakdown`` *partitions* the timeline instead (see :func:`trace.partition`).
15
+ So the weighted axis here is a share of *summed span time*, never a share of the
16
+ run, :class:`Charts` carries no ``wall_ns``, and no percentage is ever taken
17
+ against one. A chart that looked like the breakdown strip and disagreed with it
18
+ would be the worst outcome available.
19
+
20
+ :func:`charts_of` takes a population of samples rather than a span tree, so
21
+ the same four charts can describe several traces at once. Pooling
22
+ would not weaken the rule above; it strengthens it. Within one trace a sum at
23
+ least overshoots a real clock. Across traces there is no single clock to
24
+ overshoot: two trials never shared one, so their summed span time measures
25
+ nothing at all. Which is why the only totals here count spans.
26
+
27
+ Two more things are load-bearing:
28
+
29
+ * **Bins are log-spaced.** Durations here run from microseconds to minutes.
30
+ Linear bins put every span in the first bar and say nothing.
31
+ * **A span with no usable duration is excluded and counted**, never binned at
32
+ zero — :func:`trace.is_instant` is the same predicate the waterfall uses to
33
+ decide a row gets a marker instead of a bar. The count is surfaced so the
34
+ charts cannot quietly describe fewer spans than the filter panel claims.
35
+ * **A span that only wraps others is not a call**, so it is left out and counted
36
+ the same way (:data:`_WRAPPERS`). A session's duration is the whole run: drawn,
37
+ it would be the heaviest bar and the slowest kind of every trace, and say so in
38
+ every headline.
39
+
40
+ Geometry is computed here, in SVG user units against :data:`BOX`, for the same
41
+ reason :func:`trace.place` computes the waterfall's: the arithmetic runs on
42
+ nanosecond magnitudes that overflow a JS double, and staying in Python int/float
43
+ keeps it exact. Values that need formatting leave as integer nanoseconds and get
44
+ ``|nsdur`` in the template — this module emits numbers, not presentation. The
45
+ page stretches the plot to its column, so the template draws lines from these
46
+ units and places bars and labels by the percentages :class:`Box` gives: text and
47
+ rounded bar ends then keep their size at any width.
48
+
49
+ Each chart leads with the one number it is for (:class:`Headline`), computed from
50
+ the same samples it draws: never a figure the plot could not show.
51
+
52
+ The legend on a per-kind chart is a control, not a key. Clicking a kind drops it
53
+ from *that* chart, and that chart's axes rescale to what is left. This is not
54
+ :class:`trace.Filter`, which prunes spans out of the whole view — the waterfall,
55
+ the breakdown strip and the saved file all follow that one and none of them
56
+ follows this one; the spans are still in the trace, one chart is simply not
57
+ drawing them. It lives in the query string all the same
58
+ (``chart_off=<chart key>:<kind>``), for the reason the trace filter does: the
59
+ page renders from the URL, so the view can be linked and cannot drift from what
60
+ it claims to show.
61
+
62
+ Rescaling on a toggle is deliberate, and the opposite of the waterfall's rule
63
+ that its axis never moves under a filter. There the axis is a shared timeline,
64
+ and moving it would make a filter look like it had changed the timings it was
65
+ only asked to leave out. Here each chart's axis is derived from its own
66
+ population, and tool calls squeezed into the corner of an axis defined by LLM
67
+ calls that are no longer drawn show nothing at all. The cost is real, though: a
68
+ rescaled chart stops sharing its duration axis with the other three, so it says
69
+ so underneath itself.
70
+
71
+ Stdlib only, and no Flask.
72
+ """
73
+
74
+ from __future__ import annotations
75
+
76
+ import math
77
+ from dataclasses import dataclass, replace
78
+
79
+ from nullius.traces.trace import clean as _clean
80
+ from nullius.traces.trace import toggled as _toggled
81
+ from nullius.traces.trace import KIND_ORDER, all_spans, is_instant
82
+
83
+ # The SVG coordinate system every chart is drawn in. One viewBox for all four so
84
+ # they line up visually across the grid, with room on the left for value labels
85
+ # and below for the duration axis.
86
+ VIEW_W = 320.0
87
+ VIEW_H = 170.0
88
+ _PAD_L, _PAD_R, _PAD_T, _PAD_B = 40.0, 8.0, 10.0, 26.0
89
+
90
+
91
+ @dataclass(frozen=True)
92
+ class Box:
93
+ """The plot rectangle inside the viewBox — axes and labels live outside it."""
94
+
95
+ x0: float = _PAD_L
96
+ y0: float = _PAD_T
97
+ x1: float = VIEW_W - _PAD_R
98
+ y1: float = VIEW_H - _PAD_B
99
+
100
+ @property
101
+ def w(self) -> float:
102
+ return self.x1 - self.x0
103
+
104
+ @property
105
+ def h(self) -> float:
106
+ return self.y1 - self.y0
107
+
108
+ def left(self, x: float) -> float:
109
+ """A user-unit x as a percentage across the plot."""
110
+ return round((x - self.x0) / self.w * 100, 3)
111
+
112
+ def top(self, y: float) -> float:
113
+ """A user-unit y as a percentage down the plot."""
114
+ return round((y - self.y0) / self.h * 100, 3)
115
+
116
+ def width(self, w: float) -> float:
117
+ return round(w / self.w * 100, 3)
118
+
119
+ def height(self, h: float) -> float:
120
+ return round(h / self.h * 100, 3)
121
+
122
+
123
+ BOX = Box()
124
+
125
+ # How to split a decade, finest first, so a tie takes the finer one. Round steps,
126
+ # since a bin is read as a range: "2s to 5s", never "3.16s to 10s".
127
+ _SUBDIVISIONS = (
128
+ (1, 1.2, 1.5, 2, 2.5, 3, 4, 5, 6, 8),
129
+ (1, 1.5, 2, 3, 5, 7),
130
+ (1, 2, 5),
131
+ (1,),
132
+ )
133
+
134
+ # Aim for about this many bins. Fewer hides structure; many more turns a 300px
135
+ # wide plot into noise.
136
+ _TARGET_BINS = 12
137
+
138
+ # At most this many labelled ticks on the duration axis, thinned by decade.
139
+ _MAX_XTICKS = 6
140
+
141
+ # Kinds that bracket what ran inside them: a session, a turn, a namespace. Their time
142
+ # is their children's. A subagent stays, as a call the agent made and waited for.
143
+ _WRAPPERS = ("session", "group", "user_message")
144
+
145
+ # Left as a gap between neighbouring bars, in user units. Enough to read the bins
146
+ # apart, small enough that a 20-bin chart still reads as a distribution.
147
+ _BAR_GAP = 1.0
148
+
149
+ # The most durations one line turns at. Past it a line keeps every n-th, which a plot
150
+ # this wide cannot tell apart, so a trace with thousands of spans stays a small page.
151
+ _MAX_STEPS = 240
152
+
153
+ # Round tops for a share axis, in percent.
154
+ _SHARE_TOPS = (0.1, 0.2, 0.5, 1, 2, 5, 10, 20, 50, 100)
155
+
156
+
157
+ @dataclass(frozen=True)
158
+ class ChartFilter:
159
+ """Which kinds each chart is not drawing, keyed ``"<chart key>:<kind>"``.
160
+
161
+ Per chart, not per trace, and that is the whole distinction from
162
+ :class:`trace.Filter`: that one prunes spans and everything downstream
163
+ follows it, this one only decides what a single chart draws. Nothing here
164
+ ever reaches ``save-trace``, and hiding a kind in one chart leaves the other
165
+ alone — they answer different questions, and a shared toggle would redraw a
166
+ chart the reader never touched.
167
+
168
+ Immutable and canonical like its sibling, so one view has one query string.
169
+ Values it cannot parse are dropped rather than raising: this arrives from a
170
+ URL, and anyone can hand-edit one.
171
+ """
172
+
173
+ off: tuple = ()
174
+
175
+ @classmethod
176
+ def of(cls, values=()) -> "ChartFilter":
177
+ return cls(off=_clean(v for v in values if ":" in str(v)))
178
+
179
+ @property
180
+ def active(self) -> bool:
181
+ return bool(self.off)
182
+
183
+ @property
184
+ def query(self) -> dict:
185
+ """Arguments for ``url_for``, so a toggled chart is a plain link."""
186
+ return {"chart_off": list(self.off)}
187
+
188
+ def hidden(self, key: str) -> frozenset:
189
+ """The kinds switched off on the chart called ``key``."""
190
+ prefix = f"{key}:"
191
+ return frozenset(v[len(prefix):] for v in self.off if v.startswith(prefix))
192
+
193
+ def toggled(self, key: str, kind: str) -> "ChartFilter":
194
+ return ChartFilter.of(_toggled(self.off, f"{key}:{kind}"))
195
+
196
+ def cleared(self, key: str = "") -> "ChartFilter":
197
+ """Every kind drawn again — on one chart, or on all of them."""
198
+ if not key:
199
+ return ChartFilter()
200
+ prefix = f"{key}:"
201
+ return ChartFilter(off=tuple(v for v in self.off if not v.startswith(prefix)))
202
+
203
+
204
+ @dataclass(frozen=True)
205
+ class KindFacet:
206
+ """One legend chip: a kind, how many spans carry it, and whether it is drawn.
207
+
208
+ ``n`` counts the kind across the whole view rather than across what the chart
209
+ is currently drawing. A chip that read ``0`` once switched off would be a
210
+ control that hides the reason to click it again.
211
+ """
212
+
213
+ kind: str = ""
214
+ n: int = 0
215
+ off: bool = False
216
+
217
+
218
+ @dataclass(frozen=True)
219
+ class Sample:
220
+ """One span's contribution: a duration and the kind it is charged to."""
221
+
222
+ ns: int
223
+ kind: str
224
+
225
+
226
+ @dataclass(frozen=True)
227
+ class Bar:
228
+ """One histogram rectangle, already placed in user units.
229
+
230
+ In a stacked chart there is one of these per (bin, kind); ``y`` is the top of
231
+ this segment, not of the bar.
232
+ """
233
+
234
+ lo_ns: int
235
+ hi_ns: int
236
+ kind: str = "" # "" when the chart is not split by kind
237
+ count: int = 0
238
+ ns: int = 0
239
+ x: float = 0.0
240
+ y: float = 0.0
241
+ w: float = 0.0
242
+ h: float = 0.0
243
+
244
+
245
+ @dataclass(frozen=True)
246
+ class Column:
247
+ """One bin of a histogram: its segments, and what hovering it reads out."""
248
+
249
+ lo_ns: int
250
+ hi_ns: int
251
+ x: float
252
+ w: float
253
+ count: int = 0
254
+ ns: int = 0
255
+ share: str = "" # of summed span time; "" when the bars count spans
256
+ segs: tuple = () # Bars, from the baseline up
257
+
258
+
259
+ @dataclass(frozen=True)
260
+ class Series:
261
+ """One CDF polyline, ready for an SVG ``points`` attribute."""
262
+
263
+ kind: str = "" # "" for a single pooled series
264
+ label: str = ""
265
+ points: str = ""
266
+ n: int = 0
267
+ area: str = "" # the same line closed along the baseline
268
+ values: tuple = () # its share at each bin edge, 0..1
269
+ lo_ns: int = 0 # the line runs from its shortest span ...
270
+ hi_ns: int = 0 # ... to its longest: nothing happens outside them
271
+
272
+
273
+ @dataclass(frozen=True)
274
+ class ReadoutRow:
275
+ kind: str = ""
276
+ label: str = ""
277
+ share: str = ""
278
+ y: float = 0.0
279
+ on_line: bool = True # the edge is within the series' drawn line
280
+
281
+
282
+ @dataclass(frozen=True)
283
+ class Readout:
284
+ """Every series at one bin edge, and the stretch of the plot that shows it."""
285
+
286
+ ns: int
287
+ x: float
288
+ left: float
289
+ right: float
290
+ rows: tuple = ()
291
+
292
+ @property
293
+ def at(self) -> float:
294
+ """Where the edge sits inside its stretch, as a percentage of it."""
295
+ return round((self.x - self.left) / (self.right - self.left) * 100, 3) if self.right > self.left else 0.0
296
+
297
+
298
+ @dataclass(frozen=True)
299
+ class Headline:
300
+ """The chart's one number: a duration (``ns``) or a share (``text``), and what it is."""
301
+
302
+ unit: str = ""
303
+ ns: int | None = None
304
+ text: str = ""
305
+ lo_ns: int | None = None # the bin it names, when it names one
306
+ hi_ns: int | None = None
307
+
308
+
309
+ @dataclass(frozen=True)
310
+ class Marker:
311
+ """A reference line at a duration, named beside it."""
312
+
313
+ at: float
314
+ ns: int
315
+ word: str = ""
316
+
317
+
318
+ @dataclass(frozen=True)
319
+ class Tick:
320
+ """An axis tick. ``ns`` is formatted by the template; ``text`` is not a number."""
321
+
322
+ at: float # user units along the axis
323
+ ns: int | None = None
324
+ text: str = ""
325
+ anchor: str = "middle" # SVG text-anchor; the end ticks would overhang
326
+
327
+
328
+ @dataclass(frozen=True)
329
+ class Chart:
330
+ key: str = ""
331
+ title: str = ""
332
+ subtitle: str = ""
333
+ note: str = ""
334
+ form: str = "histogram" # "histogram" | "cdf"
335
+ bars: tuple = ()
336
+ series: tuple = ()
337
+ xticks: tuple = ()
338
+ yticks: tuple = ()
339
+ kinds: tuple = () # a KindFacet per kind present, in KIND_ORDER
340
+ columns: tuple = ()
341
+ readouts: tuple = ()
342
+ key_kinds: tuple = () # a key to the bars' colours, where the legend is not a control
343
+ head: Headline | None = None
344
+ marker: Marker | None = None
345
+
346
+ @property
347
+ def x_step(self) -> int | None:
348
+ """How many times longer each labelled duration is than the one before it."""
349
+ if len(self.xticks) < 2 or not self.xticks[0].ns:
350
+ return None
351
+ return round(self.xticks[1].ns / self.xticks[0].ns)
352
+
353
+ @property
354
+ def hidden_kinds(self) -> tuple:
355
+ """Kinds this chart is leaving out — what the "all ×" control undoes."""
356
+ return tuple(f.kind for f in self.kinds if f.off)
357
+
358
+
359
+ @dataclass(frozen=True)
360
+ class Charts:
361
+ items: tuple = ()
362
+ total: int = 0 # spans in the view
363
+ plotted: int = 0 # ... with a usable duration
364
+ excluded: int = 0 # ... without one
365
+ summed_ns: int = 0 # sum of plotted durations — NOT wall clock
366
+ edges: tuple = ()
367
+ box: Box = BOX
368
+
369
+ @property
370
+ def viewbox(self) -> str:
371
+ """The SVG ``viewBox``: the plot rectangle. Axis labels sit outside it, as text on the page."""
372
+ return f"{self.box.x0:g} {self.box.y0:g} {self.box.w:g} {self.box.h:g}"
373
+
374
+ @property
375
+ def has_spans(self) -> bool:
376
+ return bool(self.plotted)
377
+
378
+ @property
379
+ def wrapped(self) -> int:
380
+ """Spans left out because they only wrap others (:data:`_WRAPPERS`)."""
381
+ return self.total - self.plotted - self.excluded
382
+
383
+ @property
384
+ def note(self) -> str:
385
+ """What the charts leave out, in words, or "" when they leave out nothing."""
386
+ parts = []
387
+ if self.excluded:
388
+ one = self.excluded == 1
389
+ parts.append(
390
+ f"{self.excluded} of {self.total} spans "
391
+ f"{'has' if one else 'have'} no known duration and "
392
+ f"{'is' if one else 'are'} left out — a span with one known instant "
393
+ "is not a zero-length one."
394
+ )
395
+ if self.wrapped:
396
+ parts.append(f"{self.wrapped} of {self.total} only wrap{'s' if self.wrapped == 1 else ''} others and "
397
+ f"{'is' if self.wrapped == 1 else 'are'} left out.")
398
+ return " ".join(parts)
399
+
400
+
401
+ # The four charts, in grid order: the two time-weighted ones fill the first row,
402
+ # the two per-kind ones the second. One definition of the order, the titles and
403
+ # the axis wording — in particular "summed span time", which is the phrase that
404
+ # keeps these from reading as an accounting of the run.
405
+ _SPECS = (
406
+ ("time-hist", "Where the time is", "share of summed span time per duration bin"),
407
+ ("time-cdf", "Time concentration", "share of summed span time in spans no longer than x"),
408
+ ("kind-hist", "How many calls", "calls per duration bin, stacked by kind"),
409
+ ("kind-cdf", "Duration by kind", "share of each kind's spans no longer than x"),
410
+ )
411
+
412
+
413
+ def log_edges(lo_ns: int, hi_ns: int, target: int = _TARGET_BINS) -> tuple:
414
+ """Log-spaced bin edges covering ``[lo_ns, hi_ns]``, snapped out to decades.
415
+
416
+ Snapping outward is what makes the axis labels read ``1ms``, ``10ms``,
417
+ ``100ms`` instead of arbitrary quantiles, and it guarantees the range encloses
418
+ every sample rather than clipping the extremes.
419
+
420
+ Never degenerate. A trace whose spans all took the same time still gets a
421
+ decade of width — the same stance :func:`trace.extent_of` takes when every
422
+ span is an instant, and for the same reason: a zero-width range makes every
423
+ position NaN.
424
+ """
425
+ lo = max(int(lo_ns), 1)
426
+ hi = max(int(hi_ns), lo)
427
+ low_dec = int(math.floor(math.log10(lo)))
428
+ high_dec = int(math.ceil(math.log10(hi)))
429
+ if high_dec <= low_dec:
430
+ # One value, or a range inside a single decade boundary: widen rather
431
+ # than emit a single edge.
432
+ high_dec = low_dec + 1
433
+ decades = high_dec - low_dec
434
+
435
+ # Pick the subdivision landing nearest the target bin count. Ties go to the
436
+ # finer one, since `_SUBDIVISIONS` is ordered and `min` is stable.
437
+ steps = min(_SUBDIVISIONS, key=lambda split: abs(decades * len(split) - target))
438
+ edges = [round(step * 10 ** decade) for decade in range(low_dec, high_dec) for step in steps]
439
+ # Sorted and once each: at nanoseconds, 1 and 1.2 are one whole number.
440
+ return tuple(sorted({max(int(edge), 1) for edge in edges} | {10 ** high_dec}))
441
+
442
+
443
+ def bin_index(value: int, edges: tuple) -> int:
444
+ """Which bin ``value`` falls in — the last bin is closed on the right.
445
+
446
+ Without that, the single longest span in the trace falls off the end of the
447
+ axis it defined. Values outside the range clamp instead of raising: the edges
448
+ are built to enclose the data, so an out-of-range value means a caller mixed
449
+ two sample sets, and losing it silently would be worse than showing it at the
450
+ edge.
451
+ """
452
+ if len(edges) < 2:
453
+ return 0
454
+ last = len(edges) - 2
455
+ for i in range(last + 1):
456
+ if value < edges[i + 1]:
457
+ return max(i, 0)
458
+ return last
459
+
460
+
461
+ def _x(value: float, edges: tuple, box: Box = BOX) -> float:
462
+ """Position a duration on the log axis, in user units."""
463
+ lo, hi = math.log10(max(edges[0], 1)), math.log10(max(edges[-1], 1))
464
+ if hi <= lo:
465
+ return box.x0
466
+ frac = (math.log10(max(value, 1)) - lo) / (hi - lo)
467
+ return round(box.x0 + max(0.0, min(1.0, frac)) * box.w, 2)
468
+
469
+
470
+ def _y(frac: float, box: Box = BOX) -> float:
471
+ """A 0..1 share, measured up from the baseline, as a user-unit y."""
472
+ return round(box.y1 - max(0.0, min(1.0, frac)) * box.h, 2)
473
+
474
+
475
+ def _kinds_present(samples: list) -> tuple:
476
+ """Kinds in the samples, in legend order, unknown enum values sorted after."""
477
+ seen = {s.kind for s in samples}
478
+ known = [k for k in KIND_ORDER if k in seen]
479
+ return tuple(known + sorted(seen - set(KIND_ORDER)))
480
+
481
+
482
+ def _xticks(edges: tuple, box: Box = BOX) -> tuple:
483
+ """Ticks at decade boundaries, thinned so at most `_MAX_XTICKS` are labelled."""
484
+ decades = [
485
+ 10 ** d
486
+ for d in range(
487
+ int(math.floor(math.log10(max(edges[0], 1)))),
488
+ int(math.floor(math.log10(max(edges[-1], 1)))) + 1,
489
+ )
490
+ if edges[0] <= 10 ** d <= edges[-1]
491
+ ]
492
+ if not decades:
493
+ decades = [edges[0], edges[-1]]
494
+ stride = max(1, math.ceil(len(decades) / _MAX_XTICKS))
495
+ shown = decades[::stride]
496
+ return tuple(
497
+ Tick(
498
+ at=_x(value, edges, box),
499
+ ns=int(value),
500
+ # A centred label on the first or last tick hangs outside the
501
+ # viewBox and gets clipped, which reads as a truncated number.
502
+ anchor="start" if i == 0 else ("end" if i == len(shown) - 1 else "middle"),
503
+ )
504
+ for i, value in enumerate(shown)
505
+ )
506
+
507
+
508
+ def _share_yticks(box: Box = BOX) -> tuple:
509
+ """0/50/100% — for a cumulative axis, where the top really is everything."""
510
+ return tuple(
511
+ Tick(at=_y(frac, box), text=f"{int(frac * 100)}%")
512
+ for frac in (0.0, 0.5, 1.0)
513
+ )
514
+
515
+
516
+ def _pct(value: float) -> str:
517
+ """A share, at the precision the number deserves. Never a bare 0% for real time."""
518
+ if value <= 0:
519
+ return "0%"
520
+ if value < 0.1:
521
+ return "<0.1%"
522
+ return f"{value:.1f}%" if value < 10 else f"{value:.0f}%"
523
+
524
+
525
+ def _share_top(fullest: int, total: int) -> float:
526
+ """The round percentage a share axis tops out at: the fullest bin's, rounded up."""
527
+ share = fullest / total * 100 if total > 0 else 0.0
528
+ return next((top for top in _SHARE_TOPS if share <= top), 100)
529
+
530
+
531
+ def _scaled_yticks(top_pct: float, box: Box = BOX) -> tuple:
532
+ """Ticks for a chart whose bars are real shares on an axis of ``top_pct``.
533
+
534
+ Tall enough to read the shape, and round: a bar holding 14% of the time stands
535
+ at 14 on an axis to 20, so the top gridline is a value on the scale and never
536
+ "the tallest bar", and "100%" there would mean what it says.
537
+ """
538
+ return tuple(
539
+ Tick(at=_y(frac, box), text=_pct(top_pct * frac))
540
+ for frac in (0.0, 0.5, 1.0)
541
+ )
542
+
543
+
544
+ def _count_yticks(top: int, box: Box = BOX) -> tuple:
545
+ """0 and the tallest bin. Integers only — half a span is not a thing."""
546
+ if top <= 1:
547
+ return (Tick(at=_y(0.0, box), text="0"), Tick(at=_y(1.0, box), text=str(max(top, 1))))
548
+ mid = top // 2
549
+ ticks = [Tick(at=_y(0.0, box), text="0")]
550
+ if mid:
551
+ ticks.append(Tick(at=_y(mid / top, box), text=str(mid)))
552
+ ticks.append(Tick(at=_y(1.0, box), text=str(top)))
553
+ return tuple(ticks)
554
+
555
+
556
+ def histogram(samples: list, edges: tuple, weight: str = "count",
557
+ split: bool = False, box: Box = BOX, ceiling: float = 0.0) -> tuple:
558
+ """Bars for ``samples``, binned on ``edges``.
559
+
560
+ ``weight`` is ``"count"`` (bar height is a number of spans) or ``"time"``
561
+ (summed nanoseconds). ``split`` stacks one segment per kind within each bin.
562
+
563
+ Heights are shares of ``ceiling``, by default the tallest bin, so an empty bin
564
+ is a visible gap rather than a bar of some minimum height — the distinction
565
+ between "nothing here" and "a little here" is most of what a histogram is for.
566
+ """
567
+ n = max(len(edges) - 1, 0)
568
+ if not n or not samples:
569
+ return ()
570
+
571
+ counts = [0] * n
572
+ times = [0] * n
573
+ per_kind: list = [{} for _ in range(n)]
574
+ for sample in samples:
575
+ i = bin_index(sample.ns, edges)
576
+ counts[i] += 1
577
+ times[i] += sample.ns
578
+ cell = per_kind[i].setdefault(sample.kind, [0, 0])
579
+ cell[0] += 1
580
+ cell[1] += sample.ns
581
+
582
+ totals = times if weight == "time" else counts
583
+ top = ceiling or max(totals) or 1
584
+
585
+ bars = []
586
+ for i in range(n):
587
+ lo, hi = edges[i], edges[i + 1]
588
+ x0, x1 = _x(lo, edges, box), _x(hi, edges, box)
589
+ # The gap comes out of the bar, never off the axis: a bin's left edge is
590
+ # where its bin starts, or the bars stop lining up with the ticks.
591
+ width = max(x1 - x0 - _BAR_GAP, 0.5)
592
+ if not totals[i]:
593
+ continue
594
+ if not split:
595
+ frac = totals[i] / top
596
+ y = _y(frac, box)
597
+ bars.append(Bar(lo_ns=lo, hi_ns=hi, count=counts[i], ns=times[i],
598
+ x=x0, y=y, w=round(width, 2), h=round(box.y1 - y, 2)))
599
+ continue
600
+ # Stacked: walk the kinds in legend order so the colours do not reshuffle
601
+ # between bins, accumulating from the baseline upward.
602
+ below = 0.0
603
+ for kind in _kinds_present([Sample(ns=0, kind=k) for k in per_kind[i]]):
604
+ count, ns = per_kind[i][kind]
605
+ value = ns if weight == "time" else count
606
+ if not value:
607
+ continue
608
+ top_frac = below + value / top
609
+ y = _y(top_frac, box)
610
+ bars.append(Bar(lo_ns=lo, hi_ns=hi, kind=kind, count=count, ns=ns,
611
+ x=x0, y=y, w=round(width, 2),
612
+ h=round(_y(below, box) - y, 2)))
613
+ below = top_frac
614
+ return tuple(bars)
615
+
616
+
617
+ def _columns(bars: tuple, summed_ns: int = 0) -> tuple:
618
+ """The bars gathered into their bins. ``summed_ns``: the bars weigh time, so each
619
+ says its share of it."""
620
+ bins: dict = {}
621
+ for bar in bars:
622
+ bins.setdefault(bar.lo_ns, []).append(bar)
623
+ out = []
624
+ for segs in bins.values():
625
+ first = segs[0]
626
+ ns = sum(b.ns for b in segs)
627
+ out.append(Column(lo_ns=first.lo_ns, hi_ns=first.hi_ns, x=first.x, w=first.w, count=sum(b.count for b in segs), ns=ns,
628
+ share=_pct(ns / summed_ns * 100) if summed_ns else "", segs=tuple(segs)))
629
+ return tuple(out)
630
+
631
+
632
+ def _readouts(series: tuple, edges: tuple, box: Box = BOX) -> tuple:
633
+ """Every series at each edge, the plot split halfway between edges so the pointer need not land on a line."""
634
+ if not series:
635
+ return ()
636
+ xs = [_x(edge, edges, box) for edge in edges]
637
+ out = []
638
+ for i, edge in enumerate(edges):
639
+ left = box.x0 if i == 0 else (xs[i - 1] + xs[i]) / 2
640
+ right = box.x1 if i == len(edges) - 1 else (xs[i] + xs[i + 1]) / 2
641
+ rows = tuple(ReadoutRow(kind=s.kind, label=s.label, share=_pct(s.values[i] * 100), y=_y(s.values[i], box),
642
+ on_line=s.lo_ns <= edge <= s.hi_ns) for s in series)
643
+ out.append(Readout(ns=int(edge), x=xs[i], left=round(left, 2), right=round(right, 2), rows=rows))
644
+ return tuple(out)
645
+
646
+
647
+ def _median(samples: tuple) -> int:
648
+ """The middle span's duration (the lower one of an even count): one a span really had."""
649
+ ordered = sorted(s.ns for s in samples)
650
+ return ordered[(len(ordered) - 1) // 2]
651
+
652
+
653
+ def _half_time(samples: tuple) -> int:
654
+ """The shortest duration such that spans no longer than it hold half the summed time."""
655
+ half, held = sum(s.ns for s in samples) / 2, 0
656
+ for ns in sorted(s.ns for s in samples):
657
+ held += ns
658
+ if held >= half:
659
+ return ns
660
+ return 0
661
+
662
+
663
+ def _slowest_kind(samples: tuple) -> tuple:
664
+ """(kind, its median) for the kind whose middle span runs longest."""
665
+ grouped: dict = {}
666
+ for sample in samples:
667
+ grouped.setdefault(sample.kind, []).append(sample)
668
+ medians = {kind: _median(tuple(group)) for kind, group in grouped.items()}
669
+ kind = max(_kinds_present(samples), key=lambda k: medians[k])
670
+ return kind, medians[kind]
671
+
672
+
673
+ def _steps(ordered: list, total: float, edges: tuple, box: Box = BOX) -> str:
674
+ """The real curve, as an SVG ``points`` string: flat, then straight up at each
675
+ duration a span really took. A slope between two durations would be a share no
676
+ span ever had. It runs from the shortest span to the longest and stops: a line
677
+ along the axis on either side would be the loudest thing on a plot saying nothing.
678
+ """
679
+ turns: dict = {}
680
+ held = 0.0
681
+ for ns, weight in ordered:
682
+ held += weight
683
+ turns[ns] = held
684
+ every = max(1, math.ceil(len(turns) / _MAX_STEPS))
685
+ kept = [(ns, turns[ns]) for i, ns in enumerate(turns) if i % every == 0 or i == len(turns) - 1]
686
+ points = [f"{_x(kept[0][0], edges, box)},{_y(0.0, box)}"]
687
+ below = 0.0
688
+ for ns, reached in kept:
689
+ x = _x(ns, edges, box)
690
+ points += [f"{x},{_y(below / total, box)}", f"{x},{_y(reached / total, box)}"]
691
+ below = reached
692
+ return " ".join(points)
693
+
694
+
695
+ def _cdf_series(pairs: list, total: float, edges: tuple, box: Box = BOX, **fields) -> Series | None:
696
+ """One CDF as a :class:`Series`: its line through every span, and its share at
697
+ each bin edge, where the readout asks. ``pairs`` is [(ns, weight)]."""
698
+ if not pairs or total <= 0:
699
+ return None
700
+ ordered = sorted(pairs)
701
+ values = []
702
+ cumulative = 0.0
703
+ i = 0
704
+ for edge in edges:
705
+ while i < len(ordered) and ordered[i][0] <= edge:
706
+ cumulative += ordered[i][1]
707
+ i += 1
708
+ values.append(cumulative / total)
709
+ points = _steps(ordered, total, edges, box)
710
+ lo_ns, hi_ns = ordered[0][0], ordered[-1][0]
711
+ return Series(points=points, area=f"{points} {_x(hi_ns, edges, box)},{_y(0.0, box)}", values=tuple(values), lo_ns=lo_ns, hi_ns=hi_ns, **fields)
712
+
713
+
714
+ def cdf(samples: list, edges: tuple, weight: str = "count", box: Box = BOX) -> tuple:
715
+ """One pooled CDF series over every sample."""
716
+ if not samples:
717
+ return ()
718
+ pairs = [(s.ns, float(s.ns) if weight == "time" else 1.0) for s in samples]
719
+ series = _cdf_series(pairs, sum(w for _, w in pairs), edges, box, label="all spans", n=len(samples))
720
+ return (series,) if series else ()
721
+
722
+
723
+ def cdf_by_kind(samples: list, edges: tuple, box: Box = BOX) -> tuple:
724
+ """One CDF per kind, each normalised **within its kind**.
725
+
726
+ Normalising within the kind is what makes the lines comparable: every one
727
+ reaches 100%, so their horizontal separation is the difference in how long
728
+ that kind's calls run, not in how many of them there were. The counts are on
729
+ the legend, because that information has to survive somewhere.
730
+ """
731
+ grouped: dict = {}
732
+ for sample in samples:
733
+ grouped.setdefault(sample.kind, []).append(sample)
734
+ out = []
735
+ for kind in _kinds_present(samples):
736
+ group = grouped.get(kind) or []
737
+ series = _cdf_series([(s.ns, 1.0) for s in group], float(len(group)), edges, box, kind=kind, label=kind, n=len(group))
738
+ if series:
739
+ out.append(series)
740
+ return tuple(out)
741
+
742
+
743
+ def _visible(samples: tuple, off: frozenset) -> tuple:
744
+ """The samples a chart still draws, given the kinds switched off on it."""
745
+ return tuple(s for s in samples if s.kind not in off)
746
+
747
+
748
+ def _facets(samples: tuple, off: frozenset) -> tuple:
749
+ """One legend chip per kind in the view, counted over all of it."""
750
+ counts: dict = {}
751
+ for sample in samples:
752
+ counts[sample.kind] = counts.get(sample.kind, 0) + 1
753
+ return tuple(
754
+ KindFacet(kind=kind, n=counts.get(kind, 0), off=kind in off)
755
+ for kind in _kinds_present(samples)
756
+ )
757
+
758
+
759
+ def _edges_for(samples: tuple, fallback: tuple) -> tuple:
760
+ """Bins for a subset of the samples — the point of the legend toggle.
761
+
762
+ A chart drawing only tool calls wants the axis those calls need, not the one
763
+ the LLM calls defined before they were switched off. With nothing left to
764
+ bin it falls back to the whole range, so the empty plot still has an axis
765
+ rather than a degenerate one.
766
+ """
767
+ if not samples:
768
+ return fallback
769
+ return log_edges(min(s.ns for s in samples), max(s.ns for s in samples))
770
+
771
+
772
+ def _kind_note(off: frozenset, visible: tuple) -> str:
773
+ """What the legend has done to this chart, said underneath it; "" when nothing."""
774
+ if not visible:
775
+ return "Every kind is switched off — click a chip above to draw one again."
776
+ if not off:
777
+ return ""
778
+ names = ", ".join(sorted(off))
779
+ return (f"{names} switched off; the axes are rescaled to the rest, so "
780
+ "this one no longer shares its duration axis with the others.")
781
+
782
+
783
+ def samples_of(roots: list) -> tuple:
784
+ """(samples, total, excluded) over the spans in ``roots``.
785
+
786
+ ``roots`` is the *filtered* tree — `trace.parse` prunes before building it —
787
+ and ``all_spans`` walks all of it, not the `MAX_ROWS`-capped row list. A
788
+ chart built off the truncated set would describe a subset of the trace while
789
+ claiming to describe the view.
790
+ """
791
+ samples = []
792
+ total = 0
793
+ excluded = 0
794
+ for span in all_spans(roots):
795
+ total += 1
796
+ if is_instant(span):
797
+ excluded += 1
798
+ continue
799
+ if span.kind not in _WRAPPERS:
800
+ samples.append(Sample(ns=int(span.duration_ns), kind=span.kind))
801
+ return tuple(samples), total, excluded
802
+
803
+
804
+ def charts_for(roots: list, filt: "ChartFilter | None" = None) -> Charts:
805
+ """The four distribution charts over a filtered trace's spans."""
806
+ return charts_of(*samples_of(roots), filt=filt)
807
+
808
+
809
+ def charts_of(samples: tuple, total: int, excluded: int,
810
+ filt: "ChartFilter | None" = None) -> Charts:
811
+ """The same four charts over an already-extracted population.
812
+
813
+ Split out from :func:`charts_for` so that several traces could be pooled
814
+ without merging their span *trees*. :func:`trace.all_spans` deduplicates by
815
+ span id to guard against a parent cycle — right within one document, and
816
+ quietly wrong across several, where two traces reusing an id would lose the
817
+ duplicates without saying so. Extract each trace's samples on its own, then
818
+ concatenate them here; ids never meet.
819
+
820
+ Everything downstream of this point only ever sees durations and kinds, which
821
+ is the honest reading of what these charts describe.
822
+
823
+ ``filt`` is the legend rather than a filter on the trace: it says which kinds
824
+ the per-kind charts draw, and those charts rescale to what is left.
825
+ """
826
+ samples = tuple(Sample(ns=s.ns, kind=s.kind or "unknown") for s in samples)
827
+ filt = filt or ChartFilter()
828
+ if not samples:
829
+ return Charts(
830
+ items=tuple(Chart(key=k, title=t, subtitle=s) for k, t, s in _SPECS),
831
+ total=total, excluded=excluded,
832
+ )
833
+
834
+ edges = log_edges(min(s.ns for s in samples), max(s.ns for s in samples))
835
+ summed = sum(s.ns for s in samples)
836
+ xticks = _xticks(edges)
837
+ shares = _share_yticks() # cumulative charts only
838
+
839
+ # Coloured by kind, as the other per-kind charts and the waterfall are, on one round axis.
840
+ fullest_bin = max((b.ns for b in histogram(samples, edges, weight="time")), default=0)
841
+ top_pct = _share_top(fullest_bin, summed)
842
+ time_bars = histogram(samples, edges, weight="time", split=True, ceiling=summed * top_pct / 100)
843
+ time_columns = _columns(time_bars, summed)
844
+ fullest = max(time_columns, key=lambda c: c.ns, default=None)
845
+ half_ns = _half_time(samples)
846
+
847
+ # Each per-kind chart carries its own legend state and its own bins. The two
848
+ # ask different questions, so switching a kind off in one must leave the
849
+ # other exactly as it was.
850
+ hist_off, cdf_off = filt.hidden("kind-hist"), filt.hidden("kind-cdf")
851
+ hist_kinds, cdf_kinds = _visible(samples, hist_off), _visible(samples, cdf_off)
852
+ hist_edges, cdf_edges = _edges_for(hist_kinds, edges), _edges_for(cdf_kinds, edges)
853
+ kind_bars = histogram(hist_kinds, hist_edges, weight="count", split=True)
854
+ tallest = max(
855
+ (b.count for b in histogram(hist_kinds, hist_edges, weight="count")), default=0
856
+ )
857
+
858
+ specs = dict(zip((s[0] for s in _SPECS), _SPECS))
859
+ time_series, kind_series = cdf(samples, edges, weight="time"), cdf_by_kind(cdf_kinds, cdf_edges)
860
+ slowest = _slowest_kind(cdf_kinds) if cdf_kinds else None
861
+ built = {
862
+ "time-hist": Chart(
863
+ form="histogram", bars=time_bars, xticks=xticks,
864
+ yticks=_scaled_yticks(top_pct),
865
+ columns=time_columns,
866
+ key_kinds=_facets(samples, frozenset()),
867
+ head=Headline(text=fullest.share, unit="in spans of", lo_ns=fullest.lo_ns, hi_ns=fullest.hi_ns) if fullest else None,
868
+ ),
869
+ "time-cdf": Chart(
870
+ form="cdf", series=time_series,
871
+ xticks=xticks, yticks=shares, readouts=_readouts(time_series, edges),
872
+ head=Headline(ns=half_ns, unit="or shorter holds half the span time"),
873
+ marker=Marker(at=_x(half_ns, edges), ns=half_ns, word="half"),
874
+ ),
875
+ # Ticks and gridlines come from the *drawn* samples, not the whole set —
876
+ # an axis left at the unfiltered range is the bug the toggle exists to
877
+ # avoid. With nothing drawn there are no value labels either: a "0/1"
878
+ # count axis over an empty plot claims a measurement nobody made.
879
+ "kind-hist": Chart(
880
+ form="histogram", bars=kind_bars, xticks=_xticks(hist_edges),
881
+ yticks=_count_yticks(tallest) if hist_kinds else (),
882
+ kinds=_facets(samples, hist_off),
883
+ columns=_columns(kind_bars),
884
+ head=Headline(text=str(len(hist_kinds)), unit="call" if len(hist_kinds) == 1 else "calls") if hist_kinds else None,
885
+ note=_kind_note(hist_off, hist_kinds),
886
+ ),
887
+ "kind-cdf": Chart(
888
+ form="cdf", series=kind_series,
889
+ xticks=_xticks(cdf_edges), yticks=shares if cdf_kinds else (),
890
+ kinds=_facets(samples, cdf_off),
891
+ readouts=_readouts(kind_series, cdf_edges),
892
+ head=Headline(ns=slowest[1], unit=f"median {slowest[0]}" + (", the slowest kind" if len(kind_series) > 1 else "")) if slowest else None,
893
+ note=_kind_note(cdf_off, cdf_kinds),
894
+ ),
895
+ }
896
+ items = tuple(replace(built[key], key=key, title=specs[key][1], subtitle=specs[key][2]) for key, _, _ in _SPECS)
897
+ return Charts(items=items, total=total, plotted=len(samples), excluded=excluded,
898
+ summed_ns=summed, edges=edges)