Metadata-Version: 2.5
Name: abhyasa
Version: 0.0.9
Summary: A learning harness that makes you think: 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: ipywidgets>=8.1
Requires-Dist: python-fasthtml>=0.14
Requires-Dist: rishi>=0.1.56
Requires-Dist: rupaka>=0.0.1
Requires-Dist: vidyut>=0.4
Requires-Dist: vishalakshi>=0.1.35
Provides-Extra: demo
Requires-Dist: rupaka[check]>=0.0.1; 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: pobblebonk>=0.0.6; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: rupaka[check]>=0.0.1; extra == 'dev'
Provides-Extra: models
Requires-Dist: ramabana>=0.2.78; extra == 'models'
Provides-Extra: tick
Requires-Dist: pobblebonk>=0.0.6; extra == 'tick'
Provides-Extra: whisper
Requires-Dist: mlx-audio>=0.5; extra == 'whisper'
Description-Content-Type: text/markdown

# abhyasa


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

abhyasa (अभ्यास) means steady practice. It is a tutor that asks you questions and makes you do the thinking.
It never gives the answer first. You answer in text or by voice, and you can think aloud.
The tutor grades your reasoning, not only the result.
A learner model keeps the depth of each concept that you know, and the date of its next review.

## How it works

Each question goes through one loop:

1.  Pick. Code chooses the next concept and the depth: a due review first, then the frontier. The app shows the reason.
2.  Ask. A model writes one question at that depth, with a hidden model answer and a rubric.
3.  Struggle. You answer. A wrong try gets the first error and a nudge, but no fix. You can ask for hints, one rung at a time.
4.  Grade. The model grades the answer and the think-aloud. Code grades choice questions and code exercises.
5.  Update. Correctness and confidence move 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 the first error. Then it asks a check question.

| term | meaning |
|----|----|
| concept | one idea that you can be asked about |
| depth | 0 unseen, 1 recognise, 2 recall, 3 explain, 4 apply, 5 transfer |
| floor | the highest depth that you pass reliably |
| ceiling | the lowest depth that you failed |
| attempt | one answer, kept as a vault document |
| session | one sitting of questions; saved after each move, so you can continue it after a restart |
| journey | a goal and a path of steps to it, one concept each; you can see and change the path |
| profile | what abhyasa knows about you: background, goals, the examples that help you, pace; you see and change all of it |
| hint | one rung of a ladder of six, from the least to the most revealing |
| lesson | the smallest step that the tutor teaches after a miss |
| demo | an interactive figure for one concept: you predict, lock in, and then change the inputs |

## Install and run

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 listens on the loopback address only. These variables change the defaults:

| variable | what it sets | default |
|----|----|----|
| `ABHYASA_VAULT` | the vault file | the vault of vishalakshi |
| `ABHYASA_MODEL` | the rishi model for questions, grades, hints and lessons | `claude/sonnet` |
| `ABHYASA_STT` | the speech-to-text engine: `gemma`, `whisper`, `parakeet`, `openai` or `mlx:<repo>`. It is stronger than the Settings page. | the Settings page, then `gemma` |

## Surfaces

All surfaces use the same tutor and the same data.

### Web app

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

| block | what it does |
|----|----|
| `today` | the home page: continue, your journeys, the next review, this week |
| `journeys` | journeys: say a goal, and the tutor proposes a path of steps; move, skip, add or split a step; continue any journey |
| `history` | Your learning: each past session with what moved, what you learned each week, and Continue in the top bar (⌥C) |
| `profile` | What abhyasa knows about you: a short first conversation, your edits, and the changes that the tutor makes, each with its reason |
| `method` | The ways you learn (code, maths, analogies, worked examples, pictures, plain words): which work for you, and when to try a new one |
| `session` | one sitting with the tutor: one question at a time, with hints, confidence and “I don’t know” |
| `voice` | a mic for each text box where you answer or write; ⌥D speaks into the box in focus, on any page |
| [`settings`](https://vedicreader.github.io/abhyasa/voice.html#settings) | the speech model: pick, look up and get one; the OpenAI key; the tutor model |
| `concepts` | the list of concepts, and one page for each concept with its state |
| `graph` | the concept graph: a color for each floor, a ring when a review is due, arrows for prereqs |
| `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: “Show me a demo” on a concept page, a demo under the lesson after a miss, and one page for each demo |

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

### ramabana

The `/learn` extension gives the tutor in the terminal, beside your code.
To turn it on, make the file `~/.config/ramabana/extensions/abhyasa.py` with this line:

``` python
from abhyasa.rama import setup
```

### Notebooks

In leela or Jupyter, [`learn`](https://vedicreader.github.io/abhyasa/nb.html#learn) shows a question card. [`exercise`](https://vedicreader.github.io/abhyasa/nb.html#exercise) gives a code exercise that its tests check in the kernel.

``` python
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 the vishalakshi vault.
Each concept, attempt and session is one vault document, so other tools can search it.
Tests use a vault in a temporary folder and never open your real vault.

## 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, and it hides the result until you lock in (⌘↩). Then the controls are live, and the last line asks a new question.

- After two misses on a concept with the same kind of error, or for a concept with `visual: true` in its meta, the tutor makes a demo in the background. A model writes it as data, and rupaka checks it in a headless browser. You never wait.
- 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.
- Each prediction is kept as an attempt with `kind='demo'`, and it updates the learner model of the concept, as an answer does. A prediction with a reason counts at depth 3 (explain), and one without a reason at depth 2 (recall).

`abhyasa.demo.import_gallery(learning)` stores the rupaka gallery demos (vowel sandhi and others) for the concepts that match.

## Example

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

``` python
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` the way it teaches (code, maths, an analogy and so on). 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 raises 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
```
