v2.5.0

BambooAI 2.5.0 — the code map

Every number a report states was made by code that ran in the kernel. 2.5.0 adds a map of that code: for each chain, which inputs each cell read, what each cell made, and for each recorded number the path from the data to the RESULT line. The map is built mechanically from the committed cells and the kernel's record — no model is asked, so the same chain always gives the same map — and nothing of it enters a prompt. It shows how a number was made, not whether it is right. The executor image moves to v63.

The code map

• Opening it. When a chain has answered, its closing card carries Code map → beside the Answer, Simplified, Investigation and Plots links. The thread map (⌘M) has an eye on each chain's box that opens the same map. The map never opens on its own.
• Steps. One row per committed cell, in the order it ran: the analyst's own sentence for the step, the verbs it used (filter, group, join, bootstrap, OLS regression, …; each with a one-line gloss on hover), the data it read, and what came out — each RESULT line as a chip with its number, interval and label, marked recorded, replaced by cell n or came out empty; a printout the report cites; the figures. The inputs the chain was given stand as columns on the left — the primary file, each auxiliary file, each document, an earlier chain a follow-up builds on — with the columns the chain used; a dot marks the cells that read each one; an input the chain never read is struck through. Failed attempts and reviews keep their place in the sequence.
• Recipe diagram. For any recorded number, printout or figure: the data it rests on at the top, the tables and values the code made from it in between, the number at the bottom; arrows show what was made from what. A box opens its step; a From chain k input opens that chain's map.
• The panel. A result's panel gives its number, interval and unit, its status, what it was made from, and how it was made in order: each table or estimate with its names in the kernel, its cell, its size as the kernel recorded it, and its steps in plain words; the settings the number depends on, with the ones typed into the code marked; the choices written into the code (seeds, thresholds, resample counts, date windows); the word lists that decide what counts; the cells it rests on; a link to the cell in the notebook. A step's panel gives why the analyst took it, what it uses, what it made, what it printed and recorded, and the later steps that use it.
• Worth checking. With nothing selected, the panel lists what deserves a look, in a fixed order: the report's citations into an earlier chain's cells; reliance on an earlier chain's names; an input offered and never read, or loaded and never used; no RESULT line while the report cites a printout; a value typed into the code and how many results rest on it; results that came out empty; results replaced by later cells; word lists typed into the code. Each opens its target. The counts follow: steps, failed attempts, inputs used, results recorded, replaced, empty.
• What it can and cannot see. The map reads the code with Python's own parser and pairs each RESULT line with the statement that printed it (through a helper or a loop). It does not run the code, so it says not traced rather than guess where it cannot follow: which branch of an if ran, names computed at run time, a helper's arithmetic, changes inside library calls it does not know. A cell that does not parse keeps its row, marked not mapped. A map that cannot be built never stops a chain: the chain is answered as before, and the map says so when opened.
• Built once, kept with the chain. The map is built when the chain ends and stored in the thread file. A chain from before 2.5.0, or whose stored map is of an earlier version, gets its map built from the chain's record the first time it is opened.
• docs/CODEMAP_DESIGN.md describes the vocabulary, the rules, the stored record, the route and the known limits.

The record

• Each committed cell records the kernel's registry entries for the names it made or changed (type and description), and each RESULT record carries the cell line it was called from — through a helper, the line of the call to it. The analyst's view of the registry (NAMES) is unchanged. The run records its mode (Quick, Deep, Adaptive). A thread file from before 2.5.0 loads as before.
• Executor image v63 carries the RESULT line. A container still on v62 works: its chains get their RESULT lines paired with the code by order rather than by line, as an older run's are.

The Analyst

Three findings from an independent review of an Adaptive run:

• After a review the analyst's own note was replaced by the review's lines and lost. The note now survives a review.
• CTX.frame() and CTX.codes() returned every column as text, so dates would not compare with dates and blanks were empty strings rather than missing. Both tables now come typed, as pandas reads any file: the date columns and day as datetimes, blanks as NaN outside the text columns, chars a number. The calls that print passages are unchanged.
• A review's verdict on a cell's RESULT lines was read by the word "matches", so a review that accepted two lines and disputed one marked all three as not describing the code. The verdict is now read by its stem — ok, no, or partly when the review says both — and a partly-disputed cell is reported as such.

The README

The figure is four screenshots in one: a run beside its data, the report's figures, the chain's code map, and the recipe of one of its numbers.

Upgrading

pip install -U bambooai
bambooai serve

The first start rebuilds the executor image (v63). Threads, favourites, memory and routines are unchanged; a chain run before 2.5.0 shows its map the first time it is opened. The page loads dagre 0.8.5 from cdnjs for the recipe diagram, beside the libraries it already loads.

On the hosted service there is nothing to do.

Full changelog: v2.4.2...v2.5.0