Metadata-Version: 2.5
Name: abhyasa
Version: 0.0.16
Summary: A tutor that asks you questions: active recall, a learner model and a concept graph in your vault
Project-URL: Repository, https://github.com/vedicreader/abhyasa
Project-URL: Documentation, https://vedicreader.github.io/abhyasa/
Author-email: Karthik <karthik.rajgopal@hotmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: active-recall,learning,nbdev,spaced-repetition,vishalakshi
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.12
Requires-Dist: fastcore>=1.8
Requires-Dist: fossick>=0.1.25
Requires-Dist: gheasy>=0.0.20
Requires-Dist: ipywidgets>=8.1
Requires-Dist: litesearch>=0.1.62
Requires-Dist: mdhtml>=0.1.38
Requires-Dist: nh3>=0.3.7
Requires-Dist: python-fasthtml>=0.14
Requires-Dist: ramabana>=0.2.103
Requires-Dist: rishi>=0.1.64
Requires-Dist: rupaka>=0.0.12
Requires-Dist: shalya>=0.1.28
Requires-Dist: vidyut>=0.4
Requires-Dist: vishalakshi>=0.1.38
Provides-Extra: demo
Requires-Dist: rupaka[check]>=0.0.12; extra == 'demo'
Provides-Extra: dev
Requires-Dist: ipykernel>=7.3.0; extra == 'dev'
Requires-Dist: nbdev>=3.3.25; extra == 'dev'
Requires-Dist: notebook>=7.6.3; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: rupaka[check]>=0.0.12; extra == 'dev'
Provides-Extra: models
Requires-Dist: ramabana>=0.2.103; extra == 'models'
Provides-Extra: tick
Provides-Extra: voice
Requires-Dist: mlx-audio>=0.6.1; extra == 'voice'
Requires-Dist: pocket-tts-mlx>=0.3; extra == 'voice'
Provides-Extra: whisper
Requires-Dist: mlx-audio>=0.6.1; extra == 'whisper'
Description-Content-Type: text/markdown

# abhyasa


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

<img src="https://raw.githubusercontent.com/vedicreader/abhyasa/main/design/logo/abhyasa-icon.png" width="128" alt="abhyasa logo">

[![Download for macOS](https://img.shields.io/badge/Download_for_macOS-Abhyasa.zip-2F2722?style=for-the-badge&logo=apple&logoColor=white)](https://github.com/vedicreader/abhyasa/releases/download/mac-v0.0.15/Abhyasa.zip) [All releases](https://github.com/vedicreader/abhyasa/releases)

[![](https://github.com/vedicreader/abhyasa/actions/workflows/test.yaml/badge.svg)](https://github.com/vedicreader/abhyasa/actions/workflows/test.yaml)

abhyasa (अभ्यास) is Sanskrit for “steady practice”. It is a tutor for people who want to learn well and keep their minds active. It asks you questions, and it never gives the answer first. You answer by voice or in text, and you can think aloud. The tutor grades your reasoning, not only the result.

abhyasa keeps a learner model for each concept: how deep you know it, how well you recall it now, and when you must review it. It also learns how you learn. If code helps you more than equations, it uses code to teach a weak concept again. Sometimes it uses a different way on purpose, so that you get better at that way too.

The app needs macOS 26 on Apple Silicon. The tutor uses a language model. You choose it from a list in Settings, for example Claude, GPT or a local model. Your answers go to that model. Speech to text runs on your Mac by default. All other data stays in your vault on your Mac.

## Download

Click the Download for macOS button at the top. Then do these steps:

1.  Unzip `Abhyasa.zip`.
2.  Move `Abhyasa.app` to Applications.
3.  Open Abhyasa.
4.  Wait for the first start. The app uses uv to get Python and the abhyasa package one time. This step takes some minutes.

The app needs uv. If you do not have uv, install it with `brew install uv`. Each release has a Developer ID signature. Apple notarized each release.

### Homebrew

``` sh
brew install --cask vedicreader/tap/abhyasa
```

The cask also installs uv. To get a new version, run `brew upgrade --cask abhyasa`. To remove the app, its settings and its Python environment, run `brew uninstall --zap --cask abhyasa`. The zap does not remove your vault, because other tools use it too.

## How it works

Each question goes through the same six steps:

1.  Pick. The code chooses the next concept and the depth. A due review comes first. Then a new concept comes, if you know its prerequisites. The app shows the reason.
2.  Ask. A model writes one question at that depth, in one way to learn, such as code or an analogy. It also writes a correct answer and a rubric. You do not see them.
3.  Struggle. You answer. If your answer is wrong, the tutor shows your first error. It gives a small hint, but not the fix. You can ask for hints, one at a time.
4.  Grade. The model grades your answer and your think-aloud. The code grades choice questions. Code that you write runs in Leela.
5.  Update. The result and your confidence change the floor, the ceiling and the next review date of the concept.
6.  Teach. After a miss, the tutor teaches the smallest step that fixes your first error. Then it asks a check question.

When you say “I don’t know X”, X becomes a concept, and it comes first the next time. Progress, under You, shows your strong concepts and your weak spots with their reasons, and “Practice my weak spots” starts a session on them. A closed part shows the ways that you learn best.

| term | meaning |
|----|----|
| concept | one idea that the tutor can ask you about |
| depth | 0 unseen, 1 recognise, 2 recall, 3 explain, 4 apply, 5 transfer |
| floor | the highest depth that you pass every time |
| ceiling | the lowest depth where you failed |
| attempt | one answer, kept as a document in your vault |
| session | one sitting of questions. abhyasa saves it after each step, so you can continue it after a restart |
| walk | a path of steps, one idea for each step. A walk comes from a goal, a topic, a paper, a site, a repo or a text. You can see and change the path |
| profile | what abhyasa knows about you: your background, your goals, the examples that help you and your pace. You can see and change all of it |
| way to learn | code, maths, an analogy, a worked example, a picture or plain words. Each result counts for the way that the question used |
| gap | an idea that you said you do not know. It comes before the concept where you said it, but it does not block that concept |
| hint | one step on a ladder of six, from the least to the most help |
| lesson | the smallest step that the tutor teaches after a miss. “Another way” (⌥A) teaches it again in a different way |
| demo | an interactive figure for one concept. You predict, you lock in, and then you change the inputs |

## Learn a paper, a topic or a link as a walk

A walk takes you through one source, one idea at a time. You can make a walk from a paper in your vault, a text that you paste, a topic, or a link. Paste it into the Start box on Home. One line says what abhyasa will do with it. When two readings are likely, the box asks you to pick one.

The tutor reads the source and finds its main claim and the big ideas that explain it. A walk has 3 to 7 big ideas: 7 at most by default. You can set a smaller number in Settings, under Walks. The other ideas of the source stay on the steps as reading and in Words to know, with no check of their own. Before you start, the plan page shows each idea and the kind of check for it. You can change the kind for an idea there.

Each idea is one step. A step shows the passage from the source, word for word. It also shows a short note from the tutor and a figure from the source, if the source has one. Each step has one check:

- Short answer. You say the idea and why it holds in your own words, and the tutor grades it. The core idea in any words passes.
- Demo. You predict what a demo will do, lock in your prediction, and then change the inputs.
- Order. You put the parts of the idea in the right order.
- Notebook. For an idea that you learn with code, the step gives a notebook task, and you do it in Leela (see “Open in Leela”). abhyasa runs no code.

The tutor picks the kind that fits the idea and your profile. The step shows the reason. Reading never waits for a check. You can read the passage and press “Skip this idea” at any time. A skipped idea stays unseen in your record. A pass or a miss on a check changes your record, as an answer in a session does.

On a walk step, ⌥S sends your answer. When the check is closed, ⌥S goes to the next idea. ⌥W asks for a hint. In a demo, ⌥V keeps the state of the demo. ⌥F still shows all the keys.

### A walk from a link

On Add, choose “A link”. These links work: a web page, a documentation site, a PDF, an arXiv link or id, and a GitHub repository or file. A video link does not work. A link to your own computer or to a local network does not work either.

abhyasa fetches the link only when you press Start. The box reads only the text that you type, and it makes no network call. It reads only the pages in the folder of the link, after any redirect. It reads at most the page cap. The default is 8 pages. You can set the number in the Start box, up to the cap in Settings, under Links. The cap is 20 by default.

### A walk to a goal, from your folders and repos

Write a goal in the Start box, such as “I want to fine-tune a diffusion model. Use course22 and fastbook. Also
fastai/diffusion-nbs.” The box finds the sources that the goal names and shows them under “Sources for this goal”:

- a folder on this Mac, by its name or its path. abhyasa looks for a name only in the source folders (Settings, under
  Research). The default is `~/code/personal/orgs`, two levels down. It never searches the whole disk.
- a folder or a repo that is in your vault already;
- a public GitHub repo, as `owner/name` or as a link.

Press × to remove a source, or add one with “Add a folder, a repo or a link”. On a Mac, “Pick folders…” opens the
folder chooser. Hold ⌘ to pick more than one folder. You can also drop a PDF, a `.md` or a `.txt` file on the box. abhyasa reads nothing before you press
Start. Then it files each new folder in your vault and clones each public GitHub repo over HTTPS, then plans the walk.
abhyasa reads only `.ipynb`, `.md`, `.txt` and `.py` files
(no `.py` in a folder with notebooks), at most 400 files and 200 MB, and it never runs their code. It reads only folders
in your home folder, that you can read, with no hidden folders and no links. For one hour, the walk page shows “Added course22: 24 notebooks.” with Undo.

### Your data

Some folders are not to learn from. They are the data that you plan to run the exercises on, for example a folder of
Ramayana episodes for a walk that trains a diffusion model. In the Start box, tick “My data” on the folder. Under “Add a source”
on the walk page, choose “My data for the exercises”, or add the folder under “Your data” on the course page. Give it a short note. abhyasa does not file the folder and does not learn
from it. The course and its walks keep it, the tutor that writes a notebook step sees its name, its note and its files, and
the notebook in Leela runs on it, also a notebook that the tutor wrote before you added the folder. The walk page shows
your data under Sources. × removes it.

A path alone, such as `~/code/course22`, asks one question: “Walk through it” or “Use it for a goal”.

For a goal, the tutor plans the walk top down from the sources that you named. Each step reads its passage from one of
those documents. Steps that build your goal get a notebook check. When the goal names two or more sources, or a source
folder has more than 40 documents, an agent reads your sources and the web and finds a passage for each idea. A band on
the walk says what it reads now. “Show what it did” opens its log in the side pane, and “Stop” stops it. abhyasa keeps a
passage only when it is word for word in its document. The agent has no shell, a time limit (Settings, under Research)
and a spend limit.

When no passage is found, the step says why, for example “No page had a good quote.” Press “Find a source” to try again,
or “Pick a passage yourself”.

### A course to your goal

A goal that you type on Start makes a course. The walk that Start makes is stage 1 of the course. “Course” on the walk
opens the course page. It shows your goal, “You are here”, the next idea and the reason for it, the stages, what stands
between you and the goal, and the sources of the course.

“Ask me where I start” is the level check. It asks a few short questions about what you know. Answer each one with Yes,
A little or No, by a tap or by voice. abhyasa then plans the stages. It skips a stage of basics that you know, and it
makes a stage that you know a little short.

### Change the walk

Press “Change the walk” on the plan page, or on the rail of a step. Each change saves at once, and the Undo bar says what
changed. ⌘Z undoes it. “Earlier versions” lists the changes, and you can go back to one.

| key | what it does |
|----|----|
| W, S | move the focus to the idea above or below |
| ⇧W, ⇧S | move the idea up or down. You can also drag its grip |
| E | open the idea: its passage, its tutor note, its kind of check and its question |
| A | add an idea after it: by name, from the concept tree or from a source |
| P | split the idea into smaller ideas |
| M | merge the idea with the next idea |
| X | remove the idea. Undo gives it back |
| R | ask the tutor to write the note and the question again. A text that you changed at that time stays |
| ⌘Z | undo the last change. In a text box, ⌘Z undoes your typing |
| ⌥S | continue the walk |

“Pick another passage” shows only passages that are word for word in the walk documents. The editor also says how many
checks are hands-on. A notebook step that builds your goal does not count.

## Rabbit holes

A passage can use an idea that you do not know yet. The step then shows a “This needs” line with each idea that it needs. An idea that is not learned yet has a “Learn it” button.

You have three choices:

1.  A quick primer. A short text that you read in the side pane.
2.  A short side walk. A small walk on that idea, in the side pane.
3.  Its own session. A normal session on that idea, in a new tab.

Press ⌥B to open the offer. Then press 1, 2 or 3. A primer or a side walk opens in a pane beside the step. The paper stays on the left. On a narrow window, the side walk opens in the same tab, with “Back to the paper” at the top.

- ⌥B opens the offer for the first idea that you do not know.
- ⌥Z goes back to the paper and closes the pane. Esc also closes it.
- A side walk can open another side walk. The limit is 2 levels, and you can change it in Settings, under Walks. Past the limit, only “Own session” is left.
- The check that was open on the paper stays open. The answer that you typed there stays in the box. When the side walk ends, the paper tells you what you learned on the way.

The pane opens only pages of abhyasa. A pane address that points to another site is ignored.

## The screen guide

When you do not get a part of the page, press Caps+E (⌃⌥⇧⌘E), or press Explain in the top bar. Hold the keys to talk,
or tap them to type. Then say what you do not get, for example “I don’t get alpha bar”. When you talk, the words stay in
the box: change them if you need to, then push Return to send them.

The tutor answers on the page, as a teacher does at a whiteboard. It circles a term in a formula, points to a label in a
figure, moves the demo and speaks one short line for each step. The marks stay in place when you scroll.

- A says and draws the step again, S goes back one step, and D goes to the next step. Esc stops the board.
- A key that you type in a text box or in an editor stays in that box. The board does not move.
- You can ask a follow-up question, such as “say that more simply” or “why?”. The guide sends your last 3 questions on
  this page with it. “Follows up on: …” shows under the box, with × to start fresh. A new page or 10 minutes with no question
  clears them.
- To show a process, a cycle or a small tree, the guide draws a diagram card at the top right of the window: named boxes
  with arrows between them, with no crossings. The card never covers the page text. For a formula, the guide gives an
  example from day-to-day life instead, and marks the formula on the page.
- After a check grades your answer, ask “explain the gaps”. The guide names the problem in your answer, explains the idea
  that fixes it, and shows the path to a right answer. While you have tries left, it stops before the final answer.
- On the page of an idea, ask “show me …”. The guide opens a demo of your words in a small card. × or Esc closes it.
- A pill says where the answer is from: the tutor, your vault or the web. A quote is word for word, with its link.
- When a concept has an explainer video, the board can move the video to the right time and quote it. On a concept page,
  “Find a video” looks on YouTube, or you can paste a link.
- A natural voice reads the steps: Pocket TTS, on this Mac (`pip install abhyasa[voice]`). Its voice is `caro_davy`, and Settings,
  Speaking voice, has 20 other English voices. Download it there one time (225 MB). Until then, the browser speaks. You can also
  pick OpenAI (hosted, with your key) or the browser. The words light up as the voice says them.

The text that the guide sends to the model goes through ramabana’s guard. The guard always masks secrets. It masks personal
data only when the ramabana setting `cli.pii` is `redact` or `refuse` (the default is `off`).

## Teach a topic to a group

You can present a walk to a group, as a talk. Each idea of the walk becomes one slide. The passage and the figure, or the demo, show to the room. The tutor note becomes your speaker note. The check of the idea becomes a question for the room.

### Make a talk from a walk

On the plan of a walk, or on its path page, press “Present this walk”. The editor shows the slides in the order of the walk. A Questions slide and a recap slide come at the end. Set the minutes of your slot. A change to the talk does not change the walk.

The editor changes each slide in its row, and saves at once. W and S move the focus from slide to slide. ⇧W and ⇧S move a slide up or down, or you drag its grip. E opens the slide: its title, the points that the room sees, your speaker note, the passage, the figure, the beats and the question for the room. D duplicates the slide, X removes it, A adds a slide after it and Q adds a pause. R asks the tutor to rewrite the slide, with the chips Simpler, Add an example and Shorter. The Undo bar says what changed, and ⌘Z undoes it. “Earlier versions” lists the changes.

The beats are chips, one press of D each: the passage, the points, the figure, the demo, the question, or words to light. Drag a chip, or move it with ⇧W and ⇧S. Select words in the passage to light them on the slide.

When the walk changes, press “Make the talk again (keeps your edits)”. A part of a slide that you changed stays. A slide whose idea left the walk goes under “Not in the walk any more”, with “Put back” and “Remove”. “Make a second talk” is under More.

In this version the room answers with hands. Keep “Room phones” at “No phones”.

### The two windows

Press Present (⌥S). The presenter window shows the slide now, your notes, the next slide, the question card and a clock. The first key that you press opens the audience window. If the browser blocks it, use the link “Open the audience window” at the top.

To show the audience window on the projector, move it to the projector screen and press F in it. F fills the screen. Another key in the audience window only shows a note: the keys work in the presenter window. A reload of the audience window shows the same slide and beat. If you close the audience window, the presenter window tells you, and gives a link to open it again.

The two windows send messages only to each other, in the same browser. Each run of a talk has a new random key. Thus an audience window from an old run cannot show or change a new run.

The Abhyasa app for Mac cannot open the second window. In the app, the presenter window shows the address of the talk. Open that address in your browser to present.

### The keys of a talk

All keys work in the presenter window. They do not work while the focus is in a text box or in the demo.

| key | what it does |
|----|----|
| D, space, → or Page Down | the next beat, then the next slide. With a primer open: its next page. A clicker works too |
| A, ← or Page Up | back one beat. With a primer open: its page before |
| G, then a number | go to that slide |
| Q | ask the room, or close the question |
| R | show the right answer |
| 1 to 6 | while a question is open: the option that most hands chose |
| E | go into the demo. Esc comes out |
| X | the laser on or off. Move the pointer over the slide, and a dot shows in the audience window |
| B | blank the room screen, and back |
| ⌥S | the main button: ask the room, show the answer, close the question. On the last slide it ends the talk |
| ⌥B | open a primer beside the slide |
| ⌥Z | close the primer |
| Esc | close the open question, the demo focus or the side pane. Esc never ends the talk |

In a talk window, ⌥T, ⌥Q, ⌥R, ⌥G, ⌥C, ⌥D, ⌥1 to ⌥3 and / do nothing. Thus a key that you press by mistake does not take you away from the talk.

### Ask the room with hands

Press Q. The question and its options show in the audience window. The answer does not show. The people in the room put up their hands. Press the number of the option that most hands chose: 1 for A, 2 for B, and so on. Then press R. The right answer and the answer of most hands are lit. After R, “Talk to your neighbour” lets the room talk in pairs about the answer.

On a slide with a demo, press E to go into the demo and change it. The demo in the audience window follows each change. When you choose an answer at a gate of the demo, the room sees your answer. The room sees if your answer is right only after R. If you press “Try another”, the gate opens again in both windows.

### The side pane in a talk

Press ⌥B to see the ideas that the slide needs. Press 1 for a quick primer, or 2 for a short side walk. The primer opens beside the slide in both windows, in large type. It has no check. A long primer shows one page at a time: press D for the next page and A for the page before. While it is open, Q asks the room a question about the primer. ⌥Z closes the pane in both windows. A move to a new slide also closes it. A side walk from a talk does not show in your walks or in Continue.

### After the talk

On the last slide, press ⌥S, or press “End the talk” at the top. The audience window says “Thank you”, and the presenter window opens “After the talk”. This page shows:

- where the room was unsure: each question, with the answer that most hands chose;
- the talk, slide by slide, with the time of each slide and each primer beside it;
- “Save the recap as one file”: one HTML file with the slides, the passages, and each question with its right answer and the result of the room. It has no speaker notes and no names. Send it by mail or chat. “Look at it first” opens it in the browser;
- a follow-up walk on the ideas where the room was unsure, and the primers that you can put in the talk for the next time.

### The room does not change your learning

The answers of the room are counts in the talk. They are not your attempts. Your own pick at a demo gate in a talk is not an attempt either. A talk does not change your record, your Continue or your walks.

Settings has a Talks group. It has the minutes for each question, the time to talk to a neighbour, the share of right answers below which a slide is unsure (70% by default), and how long the laser dot stays.

## Open in Leela

abhyasa runs no code, and it does not install libraries for you. Code, a library or a command-line tool is better to learn in [Leela](https://github.com/vedicreader/leela). Leela has the tool environments, code lookup and an agent tutor.

When you add a link, tick “It is a library or a command-line tool”. This makes a tool walk. A tool walk asks short-answer and order checks here, and its code steps are notebooks in Leela.

A step that needs code has an “Open in Leela” link. The link opens Leela in a new tab, on the same walk and step. abhyasa never calls Leela. It reads the file that a running Leela writes, and it makes a link only to an address on this computer.

If Leela does not run, the step says so, and it links to the install page.

What you do in Leela comes back to the step: your code check, your prediction and your run, with its images. A check
that passes in Leela marks the step done, and the step offers “Next idea”. The walk end page shows “What you made”.

## Settings

Settings has every value that you may want to change. The values are in 12 groups:

| group | what it sets |
|----|----|
| Look | the theme and the mode |
| Learning | your pace, how many questions a session has, and how often the tutor tries a new way to teach you |
| Walks | how many ideas a walk has, how much is hands-on, how deep a side walk goes, and the length of a passage and a note |
| Talks | the minutes for each question, the time to talk to a neighbour, when a slide is unsure, and the laser |
| Checks and grading | the tries for a check, how close an answer must be to pass, hints, and how sure you must be |
| Review | when a concept comes back, and a limit for each day |
| Links | the page cap, the time for a link, and how much text abhyasa keeps |
| Code runner | the time for each test, the whole run, and the size of a file that code writes |
| Speech to text | the speech engine, the pause that ends a phrase, and the longest phrase |
| Models | the model for each tutor task, and the limit of its reply |
| Lists | how many rows each list shows |
| Prompts | the text of the tutor prompts |

Each number has a range. The page shows the range and the default next to the value, for example `3 to 30 · default 12`. A value outside its range is not kept. If your settings file has such a value, abhyasa uses the nearest end of the range and tells you on the page. Where a value is not the default, “Use the default” puts the default back. “Use the defaults for this group” does the same for the whole group. “Find a setting” filters the rows as you type.

Some guards have no setting: the closed process with no network, the check of link addresses, plain HTTP for web pages, the check of a pane address, and the rule that abhyasa answers only this computer. A change to a setting works on the next question or the next walk.

## Keyboard shortcuts

All keys are for the left hand. ⌥ is the Option key. ⌥T, ⌥Q, ⌥R and ⌥G open the tabs Today, Learn, Library and You. ⌥1 to ⌥3 open a sub-tab. To see all the keys, press ⌥F, or press ? outside a text box.

Caps+E (⌃⌥⇧⌘E) opens the screen guide. On the page Change the walk and in the talk editor, W and S move the focus, ⇧W and ⇧S
move a row, E opens it, X removes it, R rewrites it and ⌘Z undoes the last change. On the Concepts page, ⌘Z undoes the
last change that you made by hand.

If you use [Sanketa](https://github.com/vedicreader/sanketa), it shows the same keys when abhyasa is in front. abhyasa writes the pack `~/.config/sanketa/packs/abhyasa.toml` when it starts. It does not write over a pack that you made.

## Run from source

Install the package and its dependencies:

``` sh
uv sync
```

Start the web app on <http://127.0.0.1:5077>:

``` sh
uv run abhyasa
```

The app answers only requests from this Mac. These variables change the defaults:

| variable | what it sets | default |
|----|----|----|
| `ABHYASA_VAULT` | the vault file | your vault: `$VISHALAKSHI_VAULT`, then `~/.vishalakshi/vault.db` |
| `ABHYASA_MODEL` | the model id for questions, grades, hints and lessons. Choose the model in Settings. | `claude/sonnet` (Claude Sonnet) |
| `ABHYASA_STT` | the speech-to-text engine: `mlx`, `whisper`, `openai` or `mlx:<repo>`. It has priority over the Settings page. An old `gemma` reads as `mlx`. | the Settings page, then `mlx` (Qwen3-ASR 0.6B) |

## Other ways to use it

The web app, the terminal and the notebooks use the same tutor and the same data.

### The web app

The web app is made from blocks in `abhyasa/blocks`:

| block | what it does |
|----|----|
| `today` | Home: continue, the reviews that are due, your courses and walks, Teach (your talks) and the Start box |
| `history` | You → Progress: this week, what you learned each week, and each past session with what changed, in a fold. Continue (⌥C) is in the top bar |
| `jobs` | the activity chip in the top bar: what runs in the background and what ended, each with a link to its page. One event stream tells a page when a job changes |
| `profile` | what abhyasa knows about you: a short first conversation, your edits, and the changes that the tutor makes, each with its reason |
| `strengths` | on Progress: your strong concepts, your weak spots and the ways that you learn best |
| `session` | one sitting with the tutor: one question at a time, with hints, confidence and “I don’t know” |
| `voice` | a microphone for each text box. ⌥D speaks into the box that has the focus, on any page |
| [`settings`](https://vedicreader.github.io/abhyasa/learner.html#settings) | every value that you may change, in groups: the look, learning, walks, checks, review, links, speech, models, list lengths and the tutor prompts. Each number shows its range and its default. A change works on the next question |
| `concepts` | Library → Concepts: the tree of concepts, and one page for each concept with its state and Open it in your walk |
| `graph` | the concept graph. You can color it by depth, by how well you know each concept, by subject or by due date |
| `search` | one search over the `learning` shelf and the other shelves of your vault |
| [`add`](https://vedicreader.github.io/abhyasa/learner.html#add) | the Start box: read what you paste or drop, then make a walk or find concepts |
| `walk` | a walk: one step for each idea, with a passage, a note and a check |
| [`detour`](https://vedicreader.github.io/abhyasa/path.html#detour) | rabbit holes: a primer, a side walk or a session for an idea that a step needs, with the side pane |
| `demo` | interactive demos from rupaka: on a concept page, under a lesson after a miss, and one page for each demo |
| `keys` | the keyboard shortcuts (⌥F) |

The top bar has three tabs: Home (⌥T), Library (⌥R) and You (⌥G). ⌥Q goes to the Start box on Home. Library and You have sub-tabs under the page title. ⌥1, ⌥2 and ⌥3 open them. The gear at the right end opens Settings. Each page shows where you are, above its title. Esc goes up one level, and Back and Forward work.

### Notebooks

In leela or Jupyter, [`learn`](https://vedicreader.github.io/abhyasa/tutor.html#learn) shows a question card.

``` python
from abhyasa.tutor import learn
learn('reciprocal-rank-fusion')
```

## Where the data is

All data is on the `learning` shelf of your vault. Each concept, attempt and session is one document in the vault. Thus your other tools can search it. The tests use a vault in a temporary folder. They never open your real vault.

## Speech models and their licences

abhyasa does all speech on your Mac with two packages. The models download on first use, from Hugging Face.

| what | package (extra) | model | licence |
|----|----|----|----|
| speech to text | [mlx-audio](https://github.com/Blaizzy/mlx-audio) (`whisper`) | [Qwen3-ASR 0.6B, 8 bit](https://huggingface.co/mlx-community/Qwen3-ASR-0.6B-8bit) (1.0 GB), or Whisper large-v3-turbo | Apache-2.0; Whisper: MIT |
| the voice of the guide | [pocket-tts-mlx](https://github.com/jishnuvenugopal/pocket-tts-mlx) (`voice`) | [Pocket TTS](https://huggingface.co/kyutai/pocket-tts-without-voice-cloning) by Kyutai (225 MB) | code: MIT; weights: CC-BY-4.0 |

The Pocket TTS weights are by [Kyutai](https://kyutai.org), under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/) licence.
OpenAI speech is a choice in Settings. It sends your audio or the text off your Mac, and it needs your key.

## Demos

Some ideas are easier to see than to read. A demo is one interactive figure from [rupaka](https://github.com/vedicreader/rupaka). It asks you to predict first. It hides the result until you lock in (⌘↩). Then the controls work, and the last line asks a new question.

- The tutor makes a demo after two misses on a concept with the same kind of error. It also makes one for a concept with `visual: true` in its meta. The model writes the demo as data. rupaka checks it in a headless browser. You do not wait for it.
- After a miss on a concept that has a demo, the session shows the demo under the lesson.
- “Show me a demo” (⌥E) on a concept page shows the newest demo, or makes one.
- abhyasa keeps each prediction as an attempt with `kind='demo'`. A prediction changes the learner model of the concept, as an answer does. A prediction with a reason counts at depth 3 (explain). A prediction without a reason counts at depth 2 (recall).

`abhyasa.show.import_gallery(learning)` keeps the rupaka gallery demos, such as vowel sandhi, for the concepts that match.

## Example

This example runs offline. [`temp_learning`](https://vedicreader.github.io/abhyasa/learner.html#temp_learning) makes a shelf in a temporary vault, and [`Fake`](https://vedicreader.github.io/abhyasa/models.html#fake) takes the place of the model.

``` python
from abhyasa.learner import temp_learning
from abhyasa.models import Fake
from abhyasa.tutor import Tutor
```

``` python
lr = temp_learning()
lr.put('Ranking', 'Order items by a score.', 'ml')
fake = Fake({'You grade one answer': dict(correct=True, grade=8, first_error='', misconception='', feedback='Yes. Only the order counts.')},
            dflt=dict(question='Why can you compare ranks from two systems, but not their scores?', answer='Ranks share one scale.', rubric=['ranks share one scale']))
t = Tutor(lr, fake, context=False)
```

Ask the first question. `why` gives the reason for the choice, and `method` gives the way to learn that the question uses. A new concept starts at depth 3 (explain).

``` python
q = t.next()
assert q.why.startswith('next on the frontier: its prereqs are in place')   # a note on the way to learn can follow
assert q.depth == 3
print(q.question)
```

Answer with high confidence. A `solid` pass at depth 3 changes the floor to 3.

``` python
r = t.answer(q.id, 'A rank is a position, and positions use the same scale in each list.', confidence=80)
assert r.outcome == 'solid'
assert lr.concept('ranking').floor == 3
```
