abhyasa

All releases

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

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 and code exercises.
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. The Strengths page (⌥G) shows your strong concepts, your weak spots with their reasons, and the ways that you learn best. “Practice my weak spots” starts a session on your weakest concepts.

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
journey	a goal and a path to it, with one concept for each step. 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

Keyboard shortcuts

All keys are for the left hand. ⌥ is the Option key. To see all the keys, press ⌥F, or press ? outside a text box.

If you use 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:

uv sync

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

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: gemma, whisper, parakeet, openai or mlx:<repo>. It has priority over the Settings page.	the Settings page, then gemma

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	the home page: continue, your journeys, the next review and this week
journeys	say a goal, and the tutor makes a path of steps. You can move, skip, add or split a step
history	your learning: each past session with what changed, and what you learned each week. Continue (⌥C) is in the top bar
profile	what abhyasa knows about you: a short first conversation, your edits, and the changes that the tutor makes, each with its reason
strengths	your strong concepts, your weak spots and the ways that you learn best (⌥G)
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	the speech model, the OpenAI key and the model for each tutor task. You choose each model from a list of names
concepts	the list of concepts, and one page for each concept with its state
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	add concepts from a text, a vault document or vedicreader
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)

Each page shows where you are, above its title. Esc goes up one level, ⌥T goes to Today, and Back and Forward work.

ramabana

In the ramabana terminal agent, the /learn extension gives you the tutor next to your code. To turn it on, make the file ~/.config/ramabana/extensions/abhyasa.py with this line:

from abhyasa.rama import setup

Notebooks

In leela or Jupyter, learn shows a question card. exercise gives a code exercise, and its tests run in the kernel.

from abhyasa.nb import learn, exercise
learn('reciprocal-rank-fusion')
ex = exercise('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.

Demos

Some ideas are easier to see than to read. A demo is one interactive figure from 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.demo.import_gallery(learning) keeps the rupaka gallery demos, such as vowel sandhi, for the concepts that match.

Example

This example runs offline. temp_learning makes a shelf in a temporary vault, and Fake takes the place of the model.

from abhyasa.store import temp_learning
from abhyasa.llm import Fake
from abhyasa.tutor import Tutor

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).

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.

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