# rama


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

This module is a ramabana extension. It gives the `/learn` commands in
the terminal, and it uses the same
[`Tutor`](https://vedicreader.github.io/abhyasa/tutor.html#tutor) and
[`Session`](https://vedicreader.github.io/abhyasa/tutor.html#session) as
the web app. It also gives two tools, so the coding agent can add
concepts to the graph while you code.

These are the imports of the module.

## Turn it on

A ramabana extension is a file in `~/.config/ramabana/extensions/` with
a `setup(reg)` function. To turn on this extension, do these steps:

1.  Install abhyasa in the environment where ramabana runs.
2.  Make the file `~/.config/ramabana/extensions/abhyasa.py`.
3.  Put this one line in the file: `from abhyasa.rama import setup`.

<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<thead>
<tr>
<th>command</th>
<th>what it does</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>/learn [topic or slug]</code></td>
<td>start a session; name a concept to learn only that concept</td>
</tr>
<tr>
<td><code>/a &lt;answer&gt;</code></td>
<td>answer; put the think-aloud after a line with <code>--</code></td>
</tr>
<tr>
<td><code>/hint</code></td>
<td>give the next hint</td>
</tr>
<tr>
<td><code>/idk</code></td>
<td>say “I don’t know”</td>
</tr>
<tr>
<td><code>/teach</code></td>
<td>stop this question and get the lesson</td>
</tr>
<tr>
<td><code>/due</code></td>
<td>list the concepts that are due</td>
</tr>
</tbody>
</table>

The tutor uses the ramabana model call `agent.oneshot`. Thus `[jobs]` in
`config.toml` sets its route. Two tools let the coding agent add to the
graph while you code.
[`learning_note`](https://vedicreader.github.io/abhyasa/rama.html#learning_note)
files a concept that you just met.
[`learning_due`](https://vedicreader.github.io/abhyasa/rama.html#learning_due)
lists the concepts that are due.

## State and display

`_st` keeps one store, one tutor and one open session for the terminal.
The store and the tutor start on first use.

[`show_q`](https://vedicreader.github.io/abhyasa/rama.html#show_q) and
[`show_r`](https://vedicreader.github.io/abhyasa/rama.html#show_r) make
terminal text from a question and from a result.

------------------------------------------------------------------------

<a
href="https://github.com/vedicreader/abhyasa/blob/main/abhyasa/rama.py#L37"
target="_blank" style="float:right; font-size:smaller">source</a>

### show_r

``` python
def show_r(
    r
)->str:
```

*A result as terminal text.*

------------------------------------------------------------------------

<a
href="https://github.com/vedicreader/abhyasa/blob/main/abhyasa/rama.py#L31"
target="_blank" style="float:right; font-size:smaller">source</a>

### show_q

``` python
def show_q(
    q
)->str:
```

*A question as terminal text.*

## Commands

[`find`](https://vedicreader.github.io/abhyasa/rama.html#find) changes
the argument of `/learn` into a slug.
[`learn`](https://vedicreader.github.io/abhyasa/nb.html#learn) starts a
session.

------------------------------------------------------------------------

<a
href="https://github.com/vedicreader/abhyasa/blob/main/abhyasa/nb.py#L83"
target="_blank" style="float:right; font-size:smaller">source</a>

### learn

``` python
def learn(
    agent, arg:str=''
):
```

------------------------------------------------------------------------

<a
href="https://github.com/vedicreader/abhyasa/blob/main/abhyasa/rama.py#L44"
target="_blank" style="float:right; font-size:smaller">source</a>

### find

``` python
def find(
    lr, arg
)->str | None:
```

*The slug for `arg`: a slug, else the best concept hit in search, else
None.*

These commands work on the open question.
[`_need`](https://vedicreader.github.io/abhyasa/rama.html#_need) gives
an error when no question is open.

------------------------------------------------------------------------

<a
href="https://github.com/vedicreader/abhyasa/blob/main/abhyasa/rama.py#L70"
target="_blank" style="float:right; font-size:smaller">source</a>

### teach

``` python
def teach(
    agent, arg:str=''
):
```

------------------------------------------------------------------------

<a
href="https://github.com/vedicreader/abhyasa/blob/main/abhyasa/rama.py#L69"
target="_blank" style="float:right; font-size:smaller">source</a>

### idk

``` python
def idk(
    agent, arg:str=''
):
```

------------------------------------------------------------------------

<a
href="https://github.com/vedicreader/abhyasa/blob/main/abhyasa/rama.py#L68"
target="_blank" style="float:right; font-size:smaller">source</a>

### hint

``` python
def hint(
    agent, arg:str=''
):
```

------------------------------------------------------------------------

<a
href="https://github.com/vedicreader/abhyasa/blob/main/abhyasa/rama.py#L64"
target="_blank" style="float:right; font-size:smaller">source</a>

### answer

``` python
def answer(
    agent, arg:str=''
):
```

[`due`](https://vedicreader.github.io/abhyasa/rama.html#due) lists the
concepts that are due for review.

------------------------------------------------------------------------

<a
href="https://github.com/vedicreader/abhyasa/blob/main/abhyasa/rama.py#L73"
target="_blank" style="float:right; font-size:smaller">source</a>

### due

``` python
def due(
    agent:NoneType=None, arg:str=''
):
```

## Tools for the agent

The coding agent calls these tools. Their docstrings tell the agent what
each tool does.

------------------------------------------------------------------------

<a
href="https://github.com/vedicreader/abhyasa/blob/main/abhyasa/rama.py#L84"
target="_blank" style="float:right; font-size:smaller">source</a>

### learning_due

``` python
def learning_due()->str:
```

*The concepts the user has due for review.*

------------------------------------------------------------------------

<a
href="https://github.com/vedicreader/abhyasa/blob/main/abhyasa/rama.py#L78"
target="_blank" style="float:right; font-size:smaller">source</a>

### learning_note

``` python
def learning_note(
    name:str, statement:str, subject:str='code', prereqs:str=''
):
```

*File a concept the user met while coding, so abhyasa can ask about it
later. `prereqs` is comma-separated slugs.*

## Setup

[`setup`](https://vedicreader.github.io/abhyasa/rama.html#setup)
registers the commands and the tools.
[`_safe`](https://vedicreader.github.io/abhyasa/rama.html#_safe) shows
an error as text in the terminal.

------------------------------------------------------------------------

<a
href="https://github.com/vedicreader/abhyasa/blob/main/abhyasa/rama.py#L94"
target="_blank" style="float:right; font-size:smaller">source</a>

### setup

``` python
def setup(
    reg
):
```

*Register the commands and tools of abhyasa with ramabana.*

## Tests

A stand-in registry keeps the commands in a dict. A stand-in agent uses
the fake model for `oneshot`.

``` python
from abhyasa.store import temp_learning
from abhyasa.llm import Fake
fake = Fake({'You grade one answer': dict(correct=True, grade=9, first_error='', misconception='', feedback='Yes.')},
            dflt=dict(question='Why sort by score?', answer='To rank.', rubric=['rank']))
class Reg:
    def __init__(self): self.commands, self.tools = {}, []
    def command(self, n, f, help=''): self.commands[n] = f
    def tool(self, f): self.tools.append(f)
agent = AttrDict(oneshot=lambda p, sp='', job='': fake(p, sp))
_st.update(lr=temp_learning(), tutor=None, sess=None)
```

[`setup`](https://vedicreader.github.io/abhyasa/rama.html#setup)
registers all six commands, and `ans` as a second name for `a`. An
answer with no open question gives a clear message.

``` python
reg = Reg(); setup(reg)
test_eq(sorted(reg.commands), ['a', 'ans', 'due', 'hint', 'idk', 'learn', 'teach'])
test_eq(reg.commands['a'](agent, 'x'), 'No open question. Start with `/learn`.')
```

The agent files a concept. `/learn` asks about it, and `/a` grades the
answer.

``` python
assert 'Filed Ranking' in learning_note('Ranking', 'Order items by a score.', 'ml')
assert 'Why sort by score?' in reg.commands['learn'](agent, 'ranking')
assert '**solid**' in reg.commands['a'](agent, 'to rank them\n-- I think order matters')
```

A concept that was just answered is not due.

``` python
test_eq(learning_due(), 'Nothing is due.')
```

The tutor follows the newest agent, and an error other than `ValueError`
becomes one line.

``` python
agent2 = AttrDict(oneshot=lambda p, sp='', job='': fake(p, sp))
_tutor(agent2)
assert _st.agent is agent2
def boom(agent, arg=''): raise RuntimeError('the vault is busy')
test_eq(_safe(boom, agent2, ''), 'abhyasa could not do that: RuntimeError: the vault is busy')
```