# show
This module holds the ways that abhyasa shows an idea. It imports from
all the modules above it. It has three parts:
- **The screen guide**: the board that the tutor draws over a page when
you press Explain, its checks, and its three tiers of sources.
- **Demos**: the interactive figures and the 3D explainers from rupaka,
with the ladder of lessons after a miss.
- **Talks**: a walk made into slides for a group, with the questions for
the room.
Import the modules that this module uses. The heavy ones load inside the
functions that need them, so the import stays light.
## The screen guide
The screen guide: “I don’t get X”, answered with a board that the tutor
draws over the page.
The learner looks at a walk step, a concept or a video, and says “I
don’t get alpha bar”. The guide answers on the page, as a teacher does
at a whiteboard. It circles the term, draws an arrow to a label in the
figure, moves the slider of the demo, and speaks one short line for each
step.
This module is the part of the guide that has no web page:
- the **board language**: a closed list of drawing commands, each tied
to a thing on the page (an *anchor*), and the check of each line of
the model’s reply;
- the **context**: what the page shows, cleaned and cut to size;
- the **gate**: the tutor answers at once when it is sure, else it looks
in your vault, else on the web;
- the **guard**: no secret and no personal data leaves the Mac in a
model call or a web query.
The board language, its checks and the page context are in
`rupaka.board`. The `guide` block serves the board, and rupaka’s
`board.js` draws it.
Import the helpers. The model layer and ramabana load only on the first
call, so the import stays light.
### The board language
The board is in rupaka: `rupaka.board` has the language of 14 commands,
the check of each line (`check_line`), the whole reply (`parse_board`),
the page context (`clean_context`), the video cues and the stream
(`stream_board`). Its docs give each command and each rule. This module
imports these names, so `from abhyasa.show import parse_board` works.
`GUIDE_KINDS` is the old name of rupaka’s `KINDS`.
### The trust of a quote
A quote of a step stays only when it is word for word in its source.
abhyasa has its own rule for “word for word”:
[`abhyasa.sources.verbatim`](https://vedicreader.github.io/abhyasa/sources.html#verbatim)
also reads past the lines of page data, the Markdown marks and the row
numbers of `view_file`. rupaka’s default rule is plainer. So each call
of `parse_board` and `stream_board` in this module passes
[`verbatim`](https://vedicreader.github.io/abhyasa/sources.html#verbatim).
``` python
from abhyasa.sources import verbatim
```
A quote of a source with Markdown marks stays with the rule of abhyasa.
With the plain rule of rupaka, it drops:
``` python
mctx = by_id(dict(anchors=[], sources=[dict(title='DDPM', text='A **notable property** of the forward process is that it admits sampling x_t in closed form.')]))
step = json.dumps(dict(op='step', say='The paper says it.', src=1, quote='A notable property of the forward process is that it admits sampling'))
test_eq(parse_board(step, mctx, verbatim).steps[0]['quote'], dict(src=1, text='A notable property of the forward process is that it admits sampling'))
test_eq(('quote' in parse_board(step, mctx).steps[0], len(parse_board(step, mctx).dropped)), (False, 1))
```
A small context for the tests: a passage, the DDPM formula with its
tokens, a triangle figure with labels `a` and `b`, and a demo with the
input `t`. `vctx` adds a video with three cues, `shown` is what the
learner showed with the pointer, `th` is the thread of earlier turns,
and `TRY_RAW` is the learner’s last graded try of the check.
``` python
DDPM = r'q(\mathbf{x}_t\mid\mathbf{x}_0)=\mathcal{N}(\mathbf{x}_t;\sqrt{\bar\alpha_t}\mathbf{x}_0,(1-\bar\alpha_t)\mathbf{I})'
ctx = by_id(dict(anchors=[dict(id='passage', kind='passage', text='It admits sampling x_t at an arbitrary timestep t in closed form.'),
dict(id='m1', kind='formula', text=DDPM, tokens=[r'\bar\alpha_t', r'\sqrt{\bar\alpha_t}', r'\mathbf{x}_0', r'(1-\bar\alpha_t)']),
dict(id='figure', kind='figure', text='A right triangle', labels=dict(a=[100, 420, 160, 500], b=[480, 880, 540, 960]))],
demo=dict(inputs=dict(t=dict(value=500, min=0, max=1000, label='Step t')), open=False)))
vctx = by_id({**ctx, 'video': dict(id='abc123def45', cues=[[0, 'Today we add noise.'], [61.5, 'Alpha bar is the share of the signal that is left.'], [70, 'It falls as t grows.']])})
shown = [dict(kind='circle', box=[100, 50, 400, 900], anchors=['m1', 'e7', 'passage'], t=2100.4, words='why is this here'),
dict(kind='point', box=[480, 480, 520, 520], anchors=['passage'], t=800)]
th = [dict(said='I do not get alpha bar', says=['Alpha bar is the share that is left.', 'x' * 200], t='tutor'),
dict(said='why?', says=['Each step keeps a part of the signal.'], t='magic')]
TRY_RAW = dict(id='try', kind='try', text='Alpha bar grows with t.', answer='Alpha bar grows with t, because more noise is added.',
outcome='Not yet', feedback='Look at what each alpha is: a number below one.', error='Alpha bar does not grow: it is a product of numbers below one.',
gaps=['cumulative product', 'cumulative product', 'noise schedule'], state='open', left=2)
```
### Labels inside a figure
A figure is an image. Its labels (the “a” and “b” on the sides of a
triangle) are not in the page text. The guide finds them once with a
vision call and keeps their boxes for that figure. It keeps only the
boxes, never the image.
------------------------------------------------------------------------
source
### figure_labels
``` python
def figure_labels(
vision, img:bytes, alt:str=''
)->dict | None:
```
*The labels in the figure image `img`, as text to a box from 0 to 1000,
from the reply of `vision(prompt, img, sp)`. None when the* call fails
or its reply is not JSON, so that no one keeps an empty result. A key in
`alt` is masked here;
[`vision_ask`](https://vedicreader.github.io/abhyasa/show.html#vision_ask)
guards the full prompt for the model of its route.
[`FigureCache`](https://vedicreader.github.io/abhyasa/show.html#figurecache)
keeps the boxes in one JSON file, by the SHA-1 of the image bytes. A
figure that changes gets a new key.
------------------------------------------------------------------------
source
### FigureCache
``` python
def FigureCache(
path, most:int=500, empty_ttl:float=86400.0
):
```
*The label boxes of each figure, by the SHA-1 of its bytes, in the JSON
file `path`. It keeps at most `most` figures. An empty* result is kept
for `empty_ttl` seconds, and only when some figure in the file has
labels: before that, an empty reply can come from a route that lost the
picture, and the next post must ask again.
An empty result is not kept while no figure has labels. After one figure
has labels, an empty result is kept, but only for `empty_ttl` seconds:
``` python
import tempfile
```
``` python
fc = FigureCache(Path(tempfile.mkdtemp())/'figs.json', empty_ttl=60)
test_eq((fc.put('k1', {}), fc.get('k1')), (False, None))
test_eq((fc.put('k2', {'a': [1, 2, 3, 4]}), fc.put('k1', {}), fc.get('k1'), fc.get('k2')), (True, True, {}, {'a': [1, 2, 3, 4]}))
d = fc._all(); d['k1']['at'] -= 61; fc.path.write_text(json.dumps(d))
test_eq(fc.get('k1'), None) # too old: the next post asks again
```
The vision call goes through ramabana, on the job `guide_vision`:
`compose` puts the image before the text, and the call runs only when
the routed model takes a picture (`accepts`) and its route sends one
([`keeps_images`](https://vedicreader.github.io/abhyasa/show.html#keeps_images)).
[`vision_why`](https://vedicreader.github.io/abhyasa/show.html#vision_why)
says in one line why the call does not run. The prompt and the system
prompt pass
[`guard`](https://vedicreader.github.io/abhyasa/models.html#guard) for
the model of each route, so a model on this Mac gets the text as it is.
With a test model that has no routing, the call is a plain text call
that passes
[`guard`](https://vedicreader.github.io/abhyasa/models.html#guard) for a
hosted model, so a
[`Fake`](https://vedicreader.github.io/abhyasa/models.html#fake) can
answer it.
rishi’s remote one-shot makes its message only from the parts that are
dicts. So the raw image bytes and the text of `compose` do not get to
the model, and the model answers a prompt with no figure.
[`keeps_images`](https://vedicreader.github.io/abhyasa/show.html#keeps_images)
finds this with no model call: it gives the same parts to the message
code of the route and looks for the picture.
------------------------------------------------------------------------
source
### vision_ask
``` python
def vision_ask(
ask, name:str='', job:str='guide_vision'
):
```
*A vision call `(prompt, img, sp) -> str` on the ramabana job `job` (on
the model of figure labels, by default the model of hints), or None when
the routed model gets no picture
([`vision_why`](https://vedicreader.github.io/abhyasa/show.html#vision_why)).*
------------------------------------------------------------------------
source
### vision_why
``` python
def vision_why(
ask, name:str=''
)->str:
```
*Why the routed model of figure labels (`name`, else the model of
`guide_vision`) gets no picture, or ’’ when it gets one. A test model
with no routing gets one.*
------------------------------------------------------------------------
source
### keeps_images
``` python
def keeps_images(
spec
)->bool:
```
*Whether the one-shot of the route `spec` sends the picture that
`compose` puts in its prompt. Only rishi’s remote routes are checked; a
check that fails counts as yes.*
The system prompts of the guide hold no personal data, so `refuse` lets
them go:
``` python
test_eq(guard(prompt('guide.figure'), mode='refuse'), prompt('guide.figure'))
```
A vision reply that a test model gives:
``` python
from abhyasa.models import Fake
```
``` python
f = Fake({'You find the text labels': dict(labels=[dict(text='a', box=[90, 400, 160, 500])])})
test_eq(figure_labels(vision_ask(f), b'\x89PNG', 'A right triangle'), {'a': [90, 400, 160, 500]})
```
A vision call that fails gives None, not an empty result. The caller
then does not keep it, and asks again the next time.
``` python
def down(p, img, sp=''): raise TimeoutError('the model timed out')
test_eq(figure_labels(down, b'\x89PNG'), None)
```
A route whose message code drops the picture does not keep images. A
route that makes the parts into a picture keeps them. A route of another
kind is not checked:
``` python
from types import SimpleNamespace
from rishi.remote import RemoteChat, to_msg
from urai import mk_msg
```
``` python
cloud, real = SimpleNamespace(runtime='remote'), RemoteChat._oneshot_args
try:
RemoteChat._oneshot_args = lambda self, p, sp, n: ([to_msg({'role': 'user', 'content': p})], {})
test_eq(keeps_images(cloud), False)
RemoteChat._oneshot_args = lambda self, p, sp, n: ([to_msg(mk_msg(p))], {})
test_eq(keeps_images(cloud), True)
finally: RemoteChat._oneshot_args = real
test_eq(keeps_images(SimpleNamespace(runtime='claude')), True)
```
[`figure_check`](https://vedicreader.github.io/abhyasa/show.html#figure_check)
is the test of the Settings row *Figure labels*: it sends a picture with
known labels and says which labels came back.
------------------------------------------------------------------------
source
### figure_check
``` python
def figure_check(
vision, img:bytes, want:tuple=('Encoder', 'Decoder')
)->fastcore.basics.AttrDict:
```
*Whether `vision` reads each label of `want` in the picture `img`: `ok`,
the labels that it `got`, and the `missing` ones. Raise when the reply
is not JSON.*
A reply with both labels passes. An empty reply fails, and names the
missing labels:
``` python
both = json.dumps(dict(labels=[dict(text='encoder', box=[50, 290, 420, 710]), dict(text='Decoder', box=[580, 290, 950, 710])]))
test_eq(figure_check(lambda p, img, sp='': both, b'\x89PNG').ok, True)
test_eq(figure_check(lambda p, img, sp='': '{"labels": []}', b'\x89PNG'), dict(ok=False, got=[], missing=['Encoder', 'Decoder']))
```
### The prompt
The system text says the rules of the board. The parts that change (the
question, the page, the sources) come last in the request, so a
provider’s prompt cache can keep the system text.
Step 1 marks the asked part with a circle or a box, and has at most one
point for context. So a point never takes the place of the main mark.
``` python
test_eq(('mark the part that the learner asked about with a circle or a box' in GUIDE_SP, 'at most one point in step 1' in GUIDE_SP,
'Point at them when you name them' in GUIDE_SP), (True, True, False))
```
A sketch is for a figure only, and a picture of an idea goes in the side
panel: a diagram that the learner asks for is a panel, not marks on the
passage. A question about the answer starts with the problem in it, and
the final answer waits while tries are left:
``` python
test_eq(('only on a figure anchor' in GUIDE_SP, 'Never use sketch for a picture of an idea' in GUIDE_SP, 'the panel draws one' in GUIDE_SP), (True, True, True))
test_eq(('Step 1 names the problem in their answer' in GUIDE_SP, 'stop before the final answer' in GUIDE_SP,
'give the full worked solution' in GUIDE_SP, 'Step 2 explains' in GUIDE_SP), (True, True, True, False))
ex = [json.loads(l) for l in GUIDE_SP.split('An example reply', 1)[1].splitlines() if l.startswith('{')]
mine = [o for o in ex if o['op'] != 'v' and o.get('at', {}).get('a') not in ('m1', 'o1')]
test_eq([check_line(o, ctx) for o in mine], [''] * len(mine))
```
A formula gets a day-to-day example in the spoken lines. Each line is
one short sentence, and a code name is said as words:
``` python
test_eq(('day-to-day example' in GUIDE_SP, 'thrown ball' in GUIDE_SP, 'no semicolons' in GUIDE_SP, 'at most 20 words' in GUIDE_SP, 'Say a code name as words' in GUIDE_SP, len(GUIDE_SP) < 9000), (True,) * 6)
```
A process is a side panel with numbered rows. The answer of a row is in
`to`, and a head names no count. A panel has one shape: a table (which
alone can have column names), a chain, a flow of boxes, a faded example,
a wrong idea, or three stages. rupaka drops a line of another shape, so
the prompt names each shape and when to use it. The title is the small
line and the head is the big heading, so the prompt says which is which:
``` python
test_eq(('"numbered":true' in GUIDE_SP, 'the answer in "to"' in GUIDE_SP, 'no number in it' in GUIDE_SP), (True, True, True))
test_eq(('Give each panel one shape' in GUIDE_SP, 'Only a table has "cols"' in GUIDE_SP, 'and no "cols"' in GUIDE_SP, 'At most 6 rows' in GUIDE_SP), (True,) * 4)
test_eq(('"op":"node"' in GUIDE_SP, '"op":"edge"' in GUIDE_SP, '{"blank":"47"}' in GUIDE_SP, '"op":"myth"' in GUIDE_SP, '"stages":true' in GUIDE_SP, 'the big heading' in GUIDE_SP), (True,) * 6)
```
The side-panel example passes the check on a page with its output `o1`.
Each row names the words of `o1` that it comes from, no circle line
repeats them, and the line of each step names its row, so no row moves
or drops:
``` python
octx = by_id(dict(anchors=[dict(id='o1', kind='text', text='when input is tensor([18]) the target: 47 when input is tensor([18, 47]) the target: 56')]))
pe = [json.loads(l) for l in GUIDE_SP.split('An example side panel', 1)[1].splitlines() if l.startswith('{')]
test_eq([check_line(o, octx) for o in pe], [''] * len(pe))
pb = parse_board('\n'.join(json.dumps(o) for o in pe), octx)
test_eq(([[s['op'] for s in st['strokes']] for st in pb.steps], pb.dropped), ([['panel', 'row'], ['row', 'note']], []))
```
The prompt says that “show me” works on any page, that code runs in
Leela, and that the tutor never talks about its own board:
``` python
test_eq(('show me on any page' in GUIDE_SP, 'Code that runs is in Leela' in GUIDE_SP, 'Never apologise' in GUIDE_SP), (True, True, True))
```
[`focus_text`](https://vedicreader.github.io/abhyasa/show.html#focus_text)
tells the model what the learner showed with the pointer, the latest
first, with the words near that time. Step 1 must explain the first
item. The model can mark it with the box of the item, in the anchor form
`{"a": id, "box": box}`.
------------------------------------------------------------------------
source
### focus_text
``` python
def focus_text(
ctx
)->str:
```
*What the learner showed with the pointer, as lines for the request, or
’’ when they showed nothing.*
[`thread_text`](https://vedicreader.github.io/abhyasa/show.html#thread_text)
gives the earlier turns of the page to the model, the oldest first: each
question and the lines that its board said. The turns are in a fence, so
the model reads them as material, not as instructions. A rule follows:
the new question can refer to them, the board answers the new question,
and it does not give a board again that the learner saw, unless they ask
for it.
------------------------------------------------------------------------
source
### thread_text
``` python
def thread_text(
ctx
)->str:
```
*The earlier turns on this page in a fence, the oldest first, each with
what its panel showed, and the rule for them; ’’ when there are none.*
When the spoken lines of the last board were hard to read (`plain_why`),
one line says how, so the next board does better with no model call.
[`page_text`](https://vedicreader.github.io/abhyasa/show.html#page_text)
writes the anchors as lines for the model: each id, its kind and its
text, with the tokens of a formula, the labels of a figure and the range
of an input. A `try` anchor gives its fields on their own lines, and
says whether the check is open and how many tries are left.
------------------------------------------------------------------------
source
### board_prompt
``` python
def board_prompt(
ctx, said:str, sources:tuple=(), tier:str='tutor', note:str=''
)->str:
```
*The request for a board on
[`said`](https://vedicreader.github.io/abhyasa/show.html#said), with
what the learner showed
([`focus_text`](https://vedicreader.github.io/abhyasa/show.html#focus_text)),
the page of `ctx`, the earlier turns on the page
([`thread_text`](https://vedicreader.github.io/abhyasa/show.html#thread_text)),
the numbered `sources`, each in a fence, and the lines of `note`.*
------------------------------------------------------------------------
source
### panel_note
``` python
def panel_note(
ctx, said:str
)->str:
```
*The note that asks for the side panel: for “Explain ” when
the selection is in code and holds two or more numbers, and for a* typed
ask about the numbers or values (“work through the third test with its
numbers”) on a page whose code holds two or more numbers.
------------------------------------------------------------------------
source
### offer_line
``` python
def offer_line(
ctx
)->str:
```
*The offer at the end of the last step, by the kind of page: Leela on a
notebook step, Show on the page of an idea, else none.*
------------------------------------------------------------------------
source
### page_text
``` python
def page_text(
ctx
)->str:
```
*The anchors of `ctx`, one line each, with the demo and the video.*
------------------------------------------------------------------------
source
### try_text
``` python
def try_text(
a
)->str:
```
*The `try` anchor `a` as lines for the request: the state of the check,
then each field that it has.*
The request names the offer at the end of the last step by the kind of
page: “Open it in Leela” on a notebook step, “show me” on the page of an
idea, and none on another page or while a demo is on the page. “Explain
” of code with numbers asks for the side panel:
``` python
offers = [board_prompt(clean_context(c), 'x').split('\nTier:')[0].rsplit('\n', 1)[1] for c in (dict(slug='noise', leela=True), dict(slug='noise'), dict(page='/settings'))]
test_eq([('Leela' in o, 'show me' in o, 'no offer' in o) for o in offers], [(True, False, False), (False, True, True), (False, False, True)])
withdemo = board_prompt(clean_context(dict(slug='noise', demo=dict(slug='noise-demo', inputs={'t': dict(value=1)}))), 'x')
assert 'Say show me' not in withdemo and 'A demo is on the page' in withdemo # no Show offer while a demo is on the screen
code = clean_context(dict(slug='noise', anchors=[dict(id='code1', kind='code', text='assert add_noise_loss([1.0, 1.0], [1.0, -1.0], 0.5, [1.0, 1.0]) == ([1.414, 0.0], 2.0)')]))
assert 'Build the side panel from the values' in board_prompt(code, 'Explain "add_noise_loss([1.0, 1.0], [1.0, -1.0], 0.5"') # a selection of code with numbers
assert 'Build the side panel' not in board_prompt(code, 'Explain "add_noise_loss"') and 'Build the side panel' not in board_prompt(code, 'what is this')
assert 'Build the side panel from the values in the code' in board_prompt(code, 'Work through the third test with its numbers: how do we get 1.414?') # a typed ask about the values
assert 'Build the side panel' not in board_prompt(clean_context(dict(slug='noise')), 'work through it with its numbers') # no code with numbers on the page
```
The request names the focused anchors before the page, the latest first,
and says what step 1 must do:
``` python
c = clean_context(dict(anchors=ctx.anchors, focus=shown))
p = board_prompt(c, "why is this here")
test_eq(p.index('circled m1, passage') < p.index('pointed at passage') < p.index('- passage (passage)'), True)
assert 'near the words "why is this here"' in p and '{"a":"m1","box":[100,50,400,900]}' in p and 'at 2.1 s' in p
```
With no focus, the request is as before:
``` python
test_eq(focus_text(clean_context(dict(anchors=ctx.anchors))), '')
assert 'pointer' not in board_prompt(clean_context(dict(anchors=ctx.anchors)), 'x')
```
The request has the earlier turns only with a thread. They come after
the page and before the sources, with the rule:
``` python
th = [dict(said="I don't get alpha bar", says=['Alpha bar is the share that is left.'], t='tutor')]
p = board_prompt(clean_context(dict(anchors=ctx.anchors, thread=th)), 'say that more simply')
test_eq(p.index('') < p.index('Earlier on this page') < p.index('"Alpha bar is the share that is left."') < p.index('No sources.'), True)
assert THREAD_RULE in p and 'Board (tutor):' in p
assert 'Earlier on this page' not in board_prompt(clean_context(dict(anchors=ctx.anchors)), 'x')
```
A turn with its panel gives the panel in a few words, so the next board
can build on what the learner saw:
``` python
th = [dict(said='explain it with a diagram', says=['The encoder reads the input.'], t='tutor', shown='Panel "Read and write": box Encoder; box Decoder; enc → dec')]
p = board_prompt(clean_context(dict(anchors=ctx.anchors, thread=th)), 'I still do not get it')
assert 'Its panel:' in p and 'box Encoder; box Decoder' in p and 'never repeat' in p
```
When the last board said a line that is hard to read, the next prompt
says how, in one line. A plain board adds none:
``` python
th = [dict(said='why?', says=['This departs from the rule.'], t='tutor')]
p = board_prompt(clean_context(dict(anchors=ctx.anchors, thread=th)), 'I still do not get it')
assert 'hard to read: "departs from" is vague.' in p
assert 'hard to read' not in board_prompt(clean_context(dict(anchors=ctx.anchors, thread=[dict(said='why?', says=['Each step keeps less of the picture.'], t='tutor')])), 'x')
```
The try goes into the page part of the request with each of its fields:
``` python
p = board_prompt(clean_context(dict(anchors=[*ctx.anchors, TRY_RAW])), 'explain the gaps')
test_eq(("try (try): the learner's last graded try on the check. The check is open, with 2 tries left." in p,
' answer: "Alpha bar grows with t, because more noise is added."' in p, ' gaps: ["cumulative product", "noise schedule"]' in p), (True, True, True))
```
### The explainer video
A concept can have one explainer video from YouTube. The tutor finds one
with fossick’s `search_yt`, or you paste a link. fossick reads the
transcript and its timed cues (`read_yt`). The vault files the
transcript as a document (`Vault.youtube`), and the cues go into its
meta. The concept keeps the video in its provenance as `src='video'`. A
video is a source like any other: a quote from it must be word for word,
and the board names it as *video*, with its channel and title.
abhyasa reads no transcript itself. The id comes from `video_id` of
`rupaka.board`, which refuses a link that names no video.
[`find_explainer`](https://vedicreader.github.io/abhyasa/show.html#find_explainer)
searches YouTube for an idea. The query passes
[`safe_query`](https://vedicreader.github.io/abhyasa/models.html#safe_query),
as each web query that leaves the Mac does. It takes the first result
that is a video of 1 to 60 minutes.
------------------------------------------------------------------------
source
### find_explainer
``` python
def find_explainer(
name:str, topic:str='', search:NoneType=None, n:int=5
)->fastcore.basics.AttrDict | None:
```
*The first video that fossick’s `search_yt` finds for the idea `name`,
as `id`, `title`, `channel` and `url`; None when there is none.*
A fake search: a short clip and a playlist are passed over. A query with
a key does not go, also when the key is after the first 150 characters:
``` python
said = []
def fake_search(q, n): said.append(q); return [dict(id='short000001', duration=20), dict(id='PLlist', title='A list'),
dict(id='abc123def45', title='Alpha bar, simply', channel='Maths Room', duration=600)]
v = find_explainer('alpha bar', 'diffusion', search=fake_search)
test_eq((v.id, v.channel, v.url), ('abc123def45', 'Maths Room', 'https://www.youtube.com/watch?v=abc123def45'))
test_fail(lambda: find_explainer('alpha bar', 'diffusion sk-test1234567890abcdefXYZ', search=fake_search), exc=Withheld)
test_fail(lambda: find_explainer('x' * 180, 'sk-a1B2c3D4e5F6g7H8i9J0k1L2', search=fake_search), exc=Withheld)
test_eq(said, ['alpha bar diffusion explained'])
```
[`file_video`](https://vedicreader.github.io/abhyasa/show.html#file_video)
files the video and makes it the explainer of a concept. `Vault.youtube`
reads the transcript through fossick, and `read_yt` with `cues=True`
then gives the cues from fossick’s cache, with no second fetch. The link
must be public (`allow_private=False`). A concept keeps one video: a new
one takes the place of the old one.
------------------------------------------------------------------------
source
### video_of
``` python
def video_of(
lr, vid:str
)->fastcore.basics.AttrDict | None:
```
*The filed video `vid` as the guide uses it: `id`, `title`, `channel`,
`url` and `cues`. None when the vault does not have it.*
------------------------------------------------------------------------
source
### concept_video
``` python
def concept_video(
c
)->dict | None:
```
*The explainer video in the provenance of concept `c`, or None.*
------------------------------------------------------------------------
source
### set_video
``` python
def set_video(
lr, slug:str, e:NoneType=None
):
```
*Make `e` the one explainer video of concept `slug`; None takes the
video away. Under the lock of the concept.*
------------------------------------------------------------------------
source
### file_video
``` python
def file_video(
lr, url:str, slug:str=None
)->fastcore.basics.AttrDict:
```
*File the YouTube video `url` in the vault with its cues, and make it
the explainer of concept `slug`. Return its provenance entry.*
A test with fakes: fossick’s `read_yt` gives a transcript with three
cues, and the URL check passes. No call leaves the test.
``` python
import fossick.core, abhyasa.sources
from abhyasa.learner import temp_learning
```
``` python
CUES = [dict(start=0.0, end=4.0, text='Today we add noise.'), dict(start=61.5, end=69.0, text='Alpha bar is the share of the signal that is left.'),
dict(start=70.0, end=75.0, text='It falls as t grows.')]
def fake_read_yt(url, force=False, cues=False, **kw):
v = dict(title='Alpha bar, simply', channel='Maths Room', description='A short talk.', duration=600, upload_date='20260101',
source=' '.join(c['text'] for c in CUES) + f' ({url})')
return {**v, 'cues': CUES} if cues else v
real = fossick.core.read_yt, abhyasa.sources.public_url
fossick.core.read_yt, abhyasa.sources.public_url = fake_read_yt, lambda u: u
lr = temp_learning()
slug = lr.put('Alpha bar', 'How much of the clean picture is left at step t.').slug
```
Filing links the video to the concept, and the vault keeps the cues:
``` python
e = file_video(lr, 'https://youtu.be/abc123def45', slug)
test_eq((e.src, e.vid, e.channel), ('video', 'abc123def45', 'Maths Room'))
test_eq(concept_video(lr.concept(slug))['doc_id'], e.doc_id)
v = video_of(lr, 'abc123def45')
test_eq((v.title, v.cues[1]), ('Alpha bar, simply', [61.5, 'Alpha bar is the share of the signal that is left.']))
assert 'share of the signal' in lr.vault.shelf(e.shelf).document(e.doc_id).text
test_eq(file_video(lr, 'abc123def45', slug).doc_id, e.doc_id) # the same link again files nothing new
```
A second video takes the place of the first, and
[`set_video`](https://vedicreader.github.io/abhyasa/show.html#set_video)
with no entry takes it away:
``` python
file_video(lr, 'zzz123def45', slug)
test_eq([p['vid'] for p in lr.concept(slug)['provenance'] if p['src'] == 'video'], ['zzz123def45'])
set_video(lr, slug)
assert concept_video(lr.concept(slug)) is None
fossick.core.read_yt, abhyasa.sources.public_url = real
```
### A board as a hint
On a page with an open check (the anchor `check`), a board counts as one
hint on the check only when it is about the check
([`on_check`](https://vedicreader.github.io/abhyasa/show.html#on_check)):
the learner showed the check with the pointer, or named it (“check”,
“question”, “answer”, “hint”, “quiz”), or the main words of the question
are words of the check (two of them, or all when there are fewer). The
guide decides this before it asks, so it can tell the learner first. A
board that does not count may not touch the check: the request says so
(`OFF_CHECK`), and a stroke on the check drops. Then the learner keeps
the hints for a real hint.
When the page sends the learner’s last try (the anchor `try`), a
question about the try counts too: one that names the gaps, the try, a
mistake, an error, what is wrong or the feedback (`TRY_ASK`), or a
pointer on the try. Then the request says so (`ON_TRY`), and the model
follows the rule for a question about an answer. A board that does not
count gets no try.
------------------------------------------------------------------------
source
### on_check
``` python
def on_check(
ctx, said:str
)->bool:
```
*Whether a board on
[`said`](https://vedicreader.github.io/abhyasa/show.html#said) counts as
a hint on the open check of `ctx` (the anchor `check`).*
------------------------------------------------------------------------
source
### asked_words
``` python
def asked_words(
s:str
)->set:
```
*The main words of `s` (`ground.main_words`) with a light plural stem,
without the words that every question has.*
A page with an open check on the cumulative share alpha bar:
``` python
chk = clean_context(dict(anchors=[*ctx.anchors, dict(id='check', kind='check', text='Why does alpha bar fall toward zero as t grows?')]))
```
A question on the words of the check counts, and so does a question that
names the check. An off-topic question does not:
``` python
test_eq(on_check(chk, "I don't get alpha bar"), True)
test_eq(on_check(chk, 'What does this question want?'), True)
test_eq(on_check(chk, 'Who wrote the Kamba Ramayanam?'), False)
test_eq(on_check(clean_context(dict(anchors=ctx.anchors)), "I don't get alpha bar"), False) # no open check: never a hint
```
The pointer on the check counts too, whatever the words:
``` python
test_eq(on_check(clean_context(dict(chk, focus=[dict(kind='point', box=[0, 0, 10, 10], anchors=['check'])])), 'what is this'), True)
```
With the learner’s try on the page, “explain the gaps” counts. With no
try, the same words do not:
``` python
tried = clean_context(dict(anchors=[*chk.anchors, TRY_RAW]))
test_eq((on_check(tried, 'explain the gaps'), on_check(chk, 'explain the gaps'), on_check(tried, 'Who wrote the Kamba Ramayanam?')), (True, False, False))
```
### The three tiers
The guide asks in up to three tiers, and the board shows which one it
used:
1. **tutor**: the page alone. When the model says that it is sure
(`sure` of `SURE` or more), the board draws at once. The passage on
the page is source 1, so a quote from it shows as *your source*.
2. **vault**: else the guide searches your sources
([`ground`](https://vedicreader.github.io/abhyasa/sources.html#ground))
and asks again with the passages that it finds.
3. **web**: else, when research is on, it searches the web, reads the
pages, and takes a passage that is word for word in the page
(`research.pick_passage`, the gate of research). Then it asks one
last time with that passage. The page goes into your vault, linked
to the concept. The page says so at the end of the board, with Undo
([`unsave`](https://vedicreader.github.io/abhyasa/show.html#unsave)).
When no tier is sure, the best board so far shows, in the tutor’s own
words.
------------------------------------------------------------------------
source
### video_source
``` python
def video_source(
v
)->dict | None:
```
*The video `v` (from
[`video_of`](https://vedicreader.github.io/abhyasa/show.html#video_of))
as a source: its transcript, labelled* video*, with its channel and
title.*
------------------------------------------------------------------------
source
### guide_ask
``` python
def guide_ask(
ask, name:str=''
):
```
*The `ask` of the guide: the ramabana job `guide` on `name`, else on the
model of the screen guide (by default the model of hints, a fast one),
with [`guard`](https://vedicreader.github.io/abhyasa/models.html#guard)
for the* model of each route
([`guarded`](https://vedicreader.github.io/abhyasa/models.html#guarded));
a test model as it is, with
[`guard`](https://vedicreader.github.io/abhyasa/models.html#guard) for a
hosted model. A model that can stream keeps its `stream(prompt, sp)`,
with the same guard.
------------------------------------------------------------------------
source
### source_label
``` python
def source_label(
p
)->str:
```
*The label of passage `p` by its real source:* your vault\* for a vault
shelf, else the label of its source, such as *web*.\*
The guide uses the model that Settings names for the screen guide. With
no model of its own, it uses the model for hints. Here a stand-in for
[`RouteAsk`](https://vedicreader.github.io/abhyasa/models.html#routeask)
gives the job and the model of each call.
``` python
from abhyasa.models import Router
```
``` python
class Via:
"A stand-in for `RouteAsk`: each `ask` replies with its job and its model."
model = 'claude/sonnet'
def via(self, job, name='', cap=None, prepare=None):
f = lambda p, sp='': f'{job}:{name or self.model}'
f.model = name or self.model
return f
test_eq(guide_ask(Router(Via(), models=lambda: dict(hint='claude/haiku')))('hi'), 'guide:claude/haiku')
test_eq(guide_ask(Router(Via(), models=lambda: dict(hint='claude/haiku', guide='claude/opus')))('hi'), 'guide:claude/opus')
test_eq(guide_ask(Router(Via(), models=lambda: {})).model, 'claude/sonnet')
```
### Never caught unaware
The learner must always know what the guide does now, and where the text
goes. So before each step of its work,
[`explain`](https://vedicreader.github.io/abhyasa/show.html#explain)
sends a state event to `on_state`. The guide route sends each one to the
page as it comes, and the page shows it in one line, the guide bar. The
Mac overlay reads the same events. This is the one shape:
``` json
{"wait": "", "state": "reading" | "asking" | "searching" | "saving" | "drawing",
"model": "", "where": "on this Mac" | "hosted", "who": "",
"query": "", "sources": }
```
`wait` is always a full sentence, because an old page reads only `wait`.
A field that does not apply is not in the event.
[`explain`](https://vedicreader.github.io/abhyasa/show.html#explain)
sends `asking`, `searching`, `reading` and `saving`. The page itself
shows `reading` for its own read, and `drawing` when the first step
draws, so the route never sends a line that covers the board.
When the guide files a web page in the vault,
[`explain`](https://vedicreader.github.io/abhyasa/show.html#explain)
sends `{"saved": {...}}` with the document and the concept link. The
route gives the page `{"saved": {"title", "url", "undo"}}`, where `undo`
is the POST route that takes the page and its link away again
([`unsave`](https://vedicreader.github.io/abhyasa/show.html#unsave)).
[`where_of`](https://vedicreader.github.io/abhyasa/models.html#where_of)
(from `abhyasa.models`) tells who runs a model. It uses the label of
[`model_label`](https://vedicreader.github.io/abhyasa/models.html#model_label)
and the locality of ramabana (`is_local`, which knows the endpoint of an
Ollama model). The model rows in Settings use the same function.
A Claude model is hosted by Anthropic. A model that the guide does not
know counts as hosted:
``` python
test_eq(where_of('claude/sonnet'), dict(model='Claude Sonnet', where='hosted', who='Anthropic'))
test_eq(where_of(''), dict(where='hosted'))
```
A model on this Mac sends nothing off the Mac, and the line says so:
``` python
test_eq(where_of('mlx/gemma-4-e4b-it'), dict(model='Gemma 4 E4B', where='on this Mac', who=''))
test_eq(_asks(where_of('mlx/gemma-4-e4b-it'))['wait'], 'Sends your question and the page text to Gemma 4 E4B. Nothing leaves this Mac.')
test_eq(_asks(where_of('claude/sonnet'), thread=True)['wait'], 'Sends your question, the page text and your last questions on this page to Claude Sonnet.')
test_eq(_asks(where_of('claude/sonnet'), f"Sends {_n(3, 'passage')} from your vault")['wait'], 'Sends 3 passages from your vault to Claude Sonnet.')
```
[`web_sources`](https://vedicreader.github.io/abhyasa/show.html#web_sources)
is tier 3: it searches with a query that passes
[`safe_query`](https://vedicreader.github.io/abhyasa/models.html#safe_query),
reads at most 2 pages, and keeps a passage only when it is word for word
in the page. A query that may not go gives no source. A search that
gives no passage says so in a state event, and
[`explain`](https://vedicreader.github.io/abhyasa/show.html#explain)
asks once more with `NO_WEB` when the best board asked for the web: so
the board does not ask for the web that the guide already searched.
------------------------------------------------------------------------
source
### unsave
``` python
def unsave(
lr, s
)->int:
```
*Take back what the guide saved (`s`, from a
[`saved`](https://vedicreader.github.io/abhyasa/learner.html#saved)
event): the link of the page to the concept, and the page when the guide
added it. The count of changes.*
------------------------------------------------------------------------
source
### web_sources
``` python
def web_sources(
ask, ctx, said:str, search:NoneType=None, fetch:NoneType=None, lr:NoneType=None, on_state:NoneType=None
)->list:
```
*Sources from the web for
[`said`](https://vedicreader.github.io/abhyasa/show.html#said), each
with a passage that is word for word in its page. `on_state` gets a
state event before* the search (with the query word for word), before
each read and model call, and before the page goes into the vault. Then
it gets `{"saved": ...}` when the guide added the page or its link to
the concept: what
[`unsave`](https://vedicreader.github.io/abhyasa/show.html#unsave) needs
to take them away. When the web gives no passage, a state event says why
(`WEB_FAILED`, `WEB_NO_PAGE`, `WEB_NO_PASSAGE`).
A key after the first 200 characters still stops the query: the guard
reads the whole query before it is cut.
``` python
asked = []
test_eq(web_sources(None, by_id({}), 'x' * 180 + ' sk-a1B2c3D4e5F6g7H8i9J0k1L2', search=lambda q, n: asked.append(q) or []), [])
test_eq(asked, [])
```
------------------------------------------------------------------------
source
### explain
``` python
def explain(
ask, ctx, said:str, sources:tuple=(), search:NoneType=None, fetch:NoneType=None, web:bool=None,
note:NoneType=None, lr:NoneType=None, on_step:NoneType=None, stop:NoneType=None, on_state:NoneType=None
)->fastcore.basics.AttrDict:
```
*The board for
[`said`](https://vedicreader.github.io/abhyasa/show.html#said) on the
page `ctx`: from the tutor when it is sure, else from your `sources`
(the vault), else from the* web when `web` (default: the setting
`research.on`). `on_state(event)` gets a state event before each step of
the work, and `{"saved": ...}` when a web page goes into the vault (see
*Never caught unaware*); `note(text)` gets only the `wait` line. With a
model that can stream, `on_step(step, k)` gets each step of a sure tutor
board as soon as it is whole (`stream_board`). When the
`threading.Event` `stop` is set, the stream closes and no next tier
starts. `hint` is True when the board counts as a hint on the open check
([`on_check`](https://vedicreader.github.io/abhyasa/show.html#on_check));
the first state event says so.
A sure reply draws at once, from one call:
``` python
sure = '\n'.join([json.dumps(dict(op='v', n=1, sure=0.9)), json.dumps(dict(op='step', say='Alpha bar t is the share that is left.')),
json.dumps(dict(op='circle', at=dict(a='m1', tex=r'\bar\alpha_t')))])
f = Fake({'Tier: tutor': sure})
r = explain(f, dict(anchors=ctx.anchors), "I don't get alpha bar")
test_eq((r.tier, len(f.calls), r.end), ('tutor', 1, NO_SOURCE))
```
The count of steps follows the idea, not the prompt: a reply of 1, 2 or
5 steps gives a board of 1, 2 or 5 steps.
``` python
def steps_reply(n): return '\n'.join([json.dumps(dict(op='v', n=1, sure=0.9))] + [json.dumps(dict(op='step', say=f'Part {k} of alpha bar.')) for k in range(1, n + 1)])
test_eq([len(explain(Fake({'Tier: tutor': steps_reply(n)}), dict(anchors=ctx.anchors), "I don't get alpha bar").steps) for n in (1, 2, 5)], [1, 2, 5])
```
The reply of a tester’s screenshot, on the idea “Functions and the
neuron”: step 1 says that numbers x go in and one number z comes out,
but its row multiplies each input by its weight. rupaka moves that row
to step 2, whose line names it. abhyasa gives rupaka nothing about the
subject: the check uses only the words of the lines.
``` python
nctx = dict(anchors=[dict(id='passage', kind='passage', text='A neuron takes numbers x_1, ..., x_n, multiplies each by a weight w_i, adds a bias b, and outputs z.')])
seen = [dict(op='v', n=1, sure=0.9), dict(op='step', say='This page asks you to see a neuron as a function: numbers x go in, one number z comes out.'),
dict(op='panel', title='Inside one neuron', head='Turn many inputs into one output', numbered=True),
dict(op='row', cells=['Multiply each x_i by w_i'], to='w_1x_1, …, w_nx_n'),
dict(op='step', say='First it multiplies each input by its weight, then adds the products and the bias b.'), dict(op='row', cells=['Add products, then b'], to='z')]
r = explain(Fake({'Tier: tutor': '\n'.join(map(json.dumps, seen))}), nctx, "I don't get this")
test_eq([[s.get('cells') for s in st['strokes'] if s['op'] == 'row'] for st in r.steps], [[], [['Multiply each x_i by w_i'], ['Add products, then b']]])
```
An unsure reply with research off and no vault stays in the tutor’s
words:
``` python
f = Fake({'Tier: tutor': sure.replace('0.9', '0.4')})
r = explain(f, dict(anchors=ctx.anchors), "I don't get alpha bar", web=False)
test_eq((r.tier, len(f.calls)), ('tutor', 1))
```
Before its one call, the guide says who gets the question. A test model
has no name, so it is “the tutor”, and hosted:
``` python
evs = []
r = explain(Fake({'Tier: tutor': sure}), dict(anchors=ctx.anchors), "I don't get alpha bar", on_state=evs.append)
test_eq(evs, [dict(wait='Sends your question and the page text to the tutor.', state='asking', where='hosted')])
```
An unsure tutor with research on: the guide looks in the vault, searches
the web with the query word for word, reads one page, files it in the
vault and links it to the concept. Each step has its event first, and
the page that went into the vault comes in
[`saved`](https://vedicreader.github.io/abhyasa/learner.html#saved):
``` python
from abhyasa.learner import temp_learning
```
``` python
wl = temp_learning(); wl.put('Alpha bar', 'The share of the signal that is left.', 'ml')
text = 'Home. The cumulative product alpha bar t tells how much of the original signal remains after t noising steps.'
pick = dict(passage=text[6:])
webq = '\n'.join([sure.split('\n')[0], json.dumps(dict(op='step', say='A page says what alpha bar t is.', src=1, quote=text[6:]))])
f = Fake({'Tier: web': webq, 'Tier: tutor': sure.replace('0.9', '0.3'), 'Return JSON: {"passage"': pick})
evs = []
r = explain(f, dict(anchors=ctx.anchors, slug='alpha-bar', concept='Alpha bar'), "I don't get alpha bar", lr=wl, web=True, on_state=evs.append,
search=lambda q, n: [dict(title='DDPM', href='https://example.org/ddpm')], fetch=lambda u: AttrDict(url=u, title='DDPM explained', text=text))
test_eq([e.get('state') or 'saved' for e in evs], ['asking', 'searching', 'reading', 'asking', 'saving', 'saved', 'asking'])
test_eq((evs[1]['wait'], evs[1]['query']), ('Searches the web for: "I don\'t get alpha bar Alpha bar"', "I don't get alpha bar Alpha bar"))
test_eq((evs[2]['wait'], evs[-1]['wait'], evs[-1]['sources']), ('Reads example.org.', 'Sends 1 passage from the web to the tutor.', 1))
s = evs[5]['saved']
test_eq((s['title'], s['url'], s['doc_new'], s['link_new'], r.tier), ('DDPM explained', 'https://example.org/ddpm', True, True, 'web'))
```
[`unsave`](https://vedicreader.github.io/abhyasa/show.html#unsave) takes
the link and the page away again:
``` python
test_eq(unsave(wl, s), 2)
test_eq([p for p in wl.concept('alpha-bar').get('provenance') or () if p.get('src') == 'web'], [])
test_eq(unsave(wl, s), 0) # a second Undo changes nothing
```
The focus that a host sends reaches the model:
[`explain`](https://vedicreader.github.io/abhyasa/show.html#explain)
cleans the raw context, and the prompt names the circled formula:
``` python
f = Fake({'Tier: tutor': sure})
explain(f, dict(anchors=ctx.anchors, focus=[dict(kind='circle', box=[0, 0, 500, 1000], anchors=['m1'], t=900)]), "what is this")
assert 'circled m1: box [0, 0, 500, 1000] of m1, at 0.9 s' in f.calls[0][0]
```
A follow-up: “say that more simply” after a board. The host sends the
thread in the raw context, and the prompt gets the lines that the
learner heard. The first state event says that the last questions go
too. The thread passes the guard with the rest of the prompt, so a key
in an earlier question never reaches the model:
``` python
f, evs = Fake({'Tier: tutor': sure}), []
th = [dict(said="I don't get alpha bar sk-test1234567890abcdefXYZ", says=['Alpha bar t is the share that is left.', 'It falls as t grows.'], t='tutor')]
explain(f, dict(anchors=ctx.anchors, thread=th), 'say that more simply', on_state=evs.append)
p = f.calls[0][0]
assert '"Alpha bar t is the share that is left." "It falls as t grows."' in p and 'Learner: "say that more simply"' in p
assert 'sk-test1234567890' not in p and '[SECRET]' in p
test_eq(evs[0]['wait'], 'Sends your question, the page text and your last questions on this page to the tutor.')
```
With a video on the page, its cues go into the prompt, and its
transcript is a source. A `video_at` that quotes the cue draws at the
start of that cue, and the end line names the video:
``` python
vid = dict(id='abc123def45', title='Alpha bar, simply', channel='Maths Room', cues=vctx.video['cues'])
reply = '\n'.join(json.dumps(o) for o in [dict(op='v', n=1, sure=0.9), dict(op='step', say='The video says what alpha bar is.'),
dict(op='video_at', t=64, quote='the share of the signal that is left')])
f = Fake({'Tier: tutor': reply})
r = explain(f, PageContext(by_id({**ctx, 'video': vid})), "I don't get alpha bar") # as the guide route: the cues come from the vault, after the clean
assert '[62 s] Alpha bar is the share of the signal that is left.' in f.calls[0][0]
test_eq(r.steps[0]['strokes'][0]['t'], 61.5)
test_eq([(s['label'], s['title'], s['quoted']) for s in r.sources], [('video', 'Maths Room · Alpha bar, simply', True)])
test_eq(r.end, WITH_SOURCE)
```
On the page with the check, a question on the check counts as a hint,
and the first state event says so before the call:
``` python
evs = []
r = explain(Fake({'Tier: tutor': sure}), chk, "I don't get alpha bar", on_state=evs.append)
test_eq((r.hint, evs[0]['hint'], evs[0]['wait'].endswith(COUNTS)), (True, True, True))
```
An off-topic question does not count, the first event says nothing on
hints, the request tells the model to keep off the check, and a stroke
on the check drops:
``` python
evs, mark = [], sure + '\n' + json.dumps(dict(op='box', at='check'))
f = Fake({'Tier: tutor': mark})
r = explain(f, chk, 'Who wrote the Kamba Ramayanam?', on_state=evs.append)
test_eq((r.hint, 'hint' in evs[0], OFF_CHECK in f.calls[0][0]), (False, False, True))
test_eq(([s['op'] for s in r.steps[0]['strokes']], r.dropped), (['circle'], 1))
```
“Explain the gaps” with the learner’s try on the page: the request has
the try with its feedback and gaps, and says to follow the rule for an
answer. It counts as one hint. An off-topic question on the same page
sends no try:
``` python
f = Fake({'Tier: tutor': sure})
r = explain(f, dict(anchors=[*chk.anchors, TRY_RAW]), 'explain the gaps')
p = f.calls[0][0]
test_eq((r.hint, ON_TRY in p, 'Alpha bar grows with t, because more noise is added.' in p, 'Look at what each alpha is' in p, 'noise schedule' in p),
(True, True, True, True, True))
f = Fake({'Tier: tutor': sure})
explain(f, dict(anchors=[*chk.anchors, TRY_RAW]), 'Who wrote the Kamba Ramayanam?')
test_eq(('noise schedule' in f.calls[0][0], ON_TRY in f.calls[0][0]), (False, False))
```
The passages from your sources must be on the question. A passage that
names too few of its main words goes to no model, and the guide says
that it found none:
``` python
from abhyasa.sources import passage
```
``` python
class Lib:
name = 'library'
def search(self, q, k=4): return L([passage('library', 'r1', 'Rigveda 05 061 070', 'The Maruts get the gifts of the bar of gold.')])
f, evs = Fake({'Tier: tutor': sure.replace('0.9', '0.3')}), []
r = explain(f, dict(anchors=ctx.anchors, concept='Diffusion'), "I don't get alpha bar", sources=[Lib()], web=False, on_state=evs.append)
test_eq((len(f.calls), [e['wait'] for e in evs[1:]]), (1, ['Looks in your vault.', 'Found no passage on this in your vault.']))
```
A passage that passes keeps the label of its real source, not *your
vault*:
``` python
class Lib2(Lib):
def search(self, q, k=4): return L([passage('library', 'r2', 'Notes', 'Alpha bar t is the share of the signal that is left.')])
f, evs = Fake({'Tier: vault': sure, 'Tier: tutor': sure.replace('0.9', '0.3')}), []
r = explain(f, dict(anchors=ctx.anchors), "I don't get alpha bar", sources=[Lib2()], web=False, on_state=evs.append)
test_eq((r.sources[0]['label'], evs[-1]['wait']), ('library', 'Sends 1 passage from library to the tutor.'))
```
The tier and the end line come from what the board quotes. A sure vault
board that quotes nothing is in the tutor’s words, with no source:
``` python
note = 'Alpha bar t is the product of the alphas up to step t, so it falls from one toward zero as t grows.'
class Notes:
name = 'vault'
def search(self, q, k=4): return L([passage('vault:notes', 'n1', 'My DDPM notes', note)])
r = explain(Fake({'Tier: vault': sure, 'Tier: tutor': sure.replace('0.9', '0.3')}), dict(anchors=ctx.anchors), "I don't get alpha bar", sources=[Notes()], web=False)
test_eq((r.tier, r.end, [s['quoted'] for s in r.sources]), ('tutor', NO_SOURCE, [False]))
```
An unsure vault board that quotes the vault is the best board. It keeps
the sources of its own request, so the quoted source is in the list:
``` python
vq = '\n'.join([json.dumps(dict(op='v', n=1, sure=0.5)), json.dumps(dict(op='step', say='Your notes say what alpha bar is.', src=1, quote=note.split(', so')[0]))])
r = explain(Fake({'Tier: vault': vq, 'Tier: tutor': sure.replace('0.9', '0.3')}), dict(anchors=ctx.anchors), "I don't get alpha bar", sources=[Notes()], web=False)
test_eq((r.tier, r.end, [(s['label'], s['quoted']) for s in r.sources]), ('vault', WITH_SOURCE, [('your vault', True)]))
```
A vault quote of notes with Markdown marks stays, as it did before the
board moved to rupaka:
``` python
class MdNotes(Notes):
def search(self, q, k=4): return L([passage('vault:notes', 'n1', 'My DDPM notes', note.replace('product', '**product**'))])
r = explain(Fake({'Tier: vault': vq, 'Tier: tutor': sure.replace('0.9', '0.3')}), dict(anchors=ctx.anchors), "I don't get alpha bar", sources=[MdNotes()], web=False)
test_eq((r.tier, r.steps[0]['quote']['text'], [s['quoted'] for s in r.sources]), ('vault', note.split(', so')[0], [True]))
```
When the web pages have no passage, the guide says so. Then it asks once
more, and the request says that the web was searched and gave nothing:
``` python
evs = []
f = Fake({NO_WEB: sure.replace('0.9', '0.5'), 'Tier: tutor': sure.replace('0.9', '0.3').replace('"sure": 0.3', '"sure": 0.3, "need": "web"'), 'Return JSON: {"passage"': dict(passage='')})
r = explain(f, dict(anchors=ctx.anchors), "I don't get alpha bar", web=True, on_state=evs.append,
search=lambda q, n: [dict(title='DDPM', href='https://example.org/ddpm')], fetch=lambda u: AttrDict(url=u, title='DDPM', text='Nothing on it.'))
test_eq(WEB_NO_PASSAGE in [e['wait'] for e in evs], True)
test_eq((len([c for c in f.calls if 'Tier: tutor' in c[0]]), NO_WEB in f.calls[-1][0], r.sure), (2, True, .5))
```
A search with no page says that too:
``` python
evs = []
web_sources(None, by_id({}), 'alpha bar', search=lambda q, n: [], on_state=evs.append)
test_eq(evs[-1]['wait'], WEB_NO_PAGE)
```
### The board as it comes
`stream_board` is in `rupaka.board`.
[`explain`](https://vedicreader.github.io/abhyasa/show.html#explain)
passes abhyasa’s
[`verbatim`](https://vedicreader.github.io/abhyasa/sources.html#verbatim)
to it.
A board takes some seconds to write. So the tutor tier streams it, and
the first step draws while the model writes the next one. `stream_board`
reads the reply as it comes. When a new line is in, it reads the whole
lines so far again with `parse_board`, so the rules are the same as for
a whole reply. When the header says `sure` of `SURE` or more,
`on_step(step, k)` gets each step as soon as its spoken line and its
first mark are in, and again each time it gets more strokes: so the
first mark does not wait for the rest of the step (the rows of a side
panel) or for the next step. The page adds the strokes that it does not
have yet. A step that is not sure, or a reply with no header, sends
nothing, and the guide goes on to the vault and the web as before. The
board that `stream_board` returns is the truth: its first steps are the
steps that went to `on_step`.
When the stream breaks after a step went out, the board keeps the whole
lines that came, so the page does not lose what it shows.
The learner can stop: a newer question, Esc, or a closed tab. Then the
guide route sets the `threading.Event` `stop`. `stream_board` reads no
more chunks and closes the stream. So the model call ends at once, and
the next question does not wait for the backend.
`Chunked` is a test model that streams its reply in chunks of 7
characters. It writes each chunk in `events`, and the test writes each
step there too, so the order of the events shows when each step went
out.
``` python
class Chunked(Fake):
"A `Fake` that can stream: `stream(prompt, sp)` gives its reply in chunks of 7 characters, and notes each one in `events`."
def __init__(self, *a, **kw): super().__init__(*a, **kw); self.events = []
def stream(self, p, sp=''):
out = self(p, sp)
for i in range(0, len(out), 7): self.events.append('chunk'); yield out[i:i + 7]
three = '\n'.join(json.dumps(o) for o in [dict(op='v', n=1, sure=0.9), dict(op='step', say='Alpha bar t is the share that is left.'),
dict(op='circle', at=dict(a='m1', tex=r'\bar\alpha_t')), dict(op='step', say='Its root scales x0.'),
dict(op='box', at='m1'), dict(op='step', say='The rest is noise.'), dict(op='underline', at='passage')])
```
Step 1 goes out before the last chunk comes, and the steps that go out
are the steps of the final board:
``` python
f = Chunked({'Tier: tutor': three})
got = []
r = explain(f, dict(anchors=ctx.anchors), "I don't get alpha bar", on_step=lambda s, k: (got.append((k, s)), f.events.append(f'step {k}')))
ev = f.events
assert ev.index('step 1') < len(ev) - 1 - ev[::-1].index('chunk'), ev # step 1 is before the last chunk
test_eq([dict(got)[k] for k in (1, 2, 3)], r.steps) # the last copy of each step is the step of the board
test_eq((sorted(dict(got)), r.tier, len(f.calls)), ([1, 2, 3], 'tutor', 1))
test_eq(r.steps[0]['strokes'], [dict(op='circle', at=dict(a='m1', tex=r'\bar\alpha_t'))])
```
A tutor that is not sure sends no step. The board is the same as with a
model that cannot stream:
``` python
f, got = Chunked({'Tier: tutor': three.replace('0.9', '0.4')}), []
r = explain(f, dict(anchors=ctx.anchors), "I don't get alpha bar", web=False, on_step=lambda s, k: got.append(k))
test_eq((got, r.tier, len(r.steps)), ([], 'tutor', 3))
test_eq(r.steps, explain(Fake({'Tier: tutor': three.replace('0.9', '0.4')}), dict(anchors=ctx.anchors), "I don't get alpha bar", web=False).steps)
```
The stream of a test model passes the guard too: a key in the question
never reaches the model.
``` python
f = Chunked({'Tier: tutor': three})
explain(f, dict(anchors=ctx.anchors), "I don't get sk-test1234567890abcdefXYZ", on_step=lambda s, k: None)
assert f.events and 'sk-test1234567890abcdefXYZ' not in f.calls[0][0] and '[SECRET]' in f.calls[0][0]
```
A streamed step keeps its quote of a page passage with Markdown marks
too:
``` python
pg = dict(source='DDPM', anchors=[dict(id='passage', kind='passage', text='It **admits sampling** x_t at an arbitrary timestep t in closed form.')])
qt = '\n'.join(json.dumps(o) for o in [dict(op='v', n=1, sure=0.9), dict(op='step', say='The paper says it.', src=1, quote='It admits sampling x_t at an arbitrary timestep t in closed form'),
dict(op='underline', at='passage')])
got = []
r = explain(Chunked({'Tier: tutor': qt}), pg, 'why closed form?', on_step=lambda s, k: got.append(s))
test_eq((r.steps[0]['quote']['src'], got[-1].get('quote'), r.end), (1, r.steps[0]['quote'], WITH_SOURCE))
```
### The board in the page
rupaka’s `board.js`
([`rupaka.board.assets()`](https://vedicreader.github.io/rupaka/board.html#assets))
draws the checked board. The app serves it at `/assets/board.js`. It
takes its numbers from Clicky (github.com/farzaa/clicky, MIT):
- **The pointer.** A small triangle in the board ink flies to each mark
on a quadratic arc. The arc lifts by `min(d * 0.2, 80)` px, the flight
takes `clamp(d / 800, 0.6, 1.4)` s, and the easing is smoothstep. The
pointer turns to its path and grows to 1.3x as it lands, then settles
on a spring (response 0.4, damping 0.6). A mark draws from its tip.
- **The glow.** A `box` is a soft ring and halo that blooms and then
settles. It stays 10 px outside the text, so it never cuts it.
- **The marker.** A `circle` on a formula part or on words adds a wide
marker stroke through the glyphs. Its blend mode comes from the
surface under it: `multiply` on a light surface, `screen` on a dark
one. A white figure in dark mode still uses `multiply`.
- **The chips.** A
[`label`](https://vedicreader.github.io/abhyasa/sources.html#label) is
a pastel chip with a coloured bar at its left, dark text in a sans
font, and a thin leader line that ends in a dot on the part. Each
label in a step has its own pastel. The chip pops in on a spring, and
it never covers its target.
- **The strokes.** Rings, underlines and sketches are perfect-freehand
strokes with pressure, and they draw on as a pen does. An arrow is one
light Rough.js stroke with a filled head. Marks from earlier steps
fade to 45 %, and the glow of an earlier step goes.
- **The side panel.** The example of Explain is a card on warm paper at
the top right of the window, in a hand font, with the values in
monospace. Each step adds its row: the circle on the value on the page
at its word, the curve from it 120 ms later, the row when the curve
lands, then each cell 80 ms after the one before. Rows stay for the
next steps; their curves fade. A new beat (a new `panel` line) has its
own title. While the panel shows, the page column moves left, so the
panel never covers a mark. Below 1100 px the panel stands in the page,
under the marked part.
- **The scroll.** Before a step draws, the page scrolls its first mark
into view when the mark is off screen or under the strip.
- **The voice.** Each word of the spoken line in the strip lights up
when it is said.
- **The state line.** While the guide works, the strip shows one line:
the `wait` text of the latest state event, a chip that says *on this
Mac* or *hosted · *, the seconds after 3 s while the model
writes, and Stop. Stop and Esc end the request, so the model stream
closes. The caption of a board names its model, and has Voice off and
Stop. The end shows what the guide saved, with Undo, and the hint line
when the board counted as a hint on the open check.
- **The figure.** The picture of a figure goes to the vision model only
when the question is about it (the learner showed it, or the question
names it), and the line says so first: “The guide sends this figure to
to find its labels.”
With `prefers-reduced-motion`, the pointer jumps to its mark, and the
marks and chips fade in for 150 ms. Text from the model goes in with
`textContent` only.
### Host hooks: the board on another page
Leela and other hosts use the same board. `play` takes the hooks of the
page in `host`. Each hook is optional, and the defaults keep the
behaviour of abhyasa:
``` js
abhyasaBoard.play(board, {labels, fast, quiet, auto, host: {resolve, speak, demo, assets}})
```