# aimagic


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

## Install

Clone this repo, and then:

``` sh
cd aimagic
pip install -e .
mkdir -p $VIRTUAL_ENV/share/jupyter/nbextensions
rm -f $VIRTUAL_ENV/share/jupyter/nbextensions/nbmeta.js
ln -s ${PWD}/static/nbmeta.js $VIRTUAL_ENV/share/jupyter/nbextensions/
mkdir -p $VIRTUAL_ENV/etc/jupyter/nbconfig/notebook.d
rm -f $VIRTUAL_ENV/etc/jupyter/nbconfig/notebook.d/nbmeta.json
ln -s ${PWD}/jupyter-config/nbmeta.json $VIRTUAL_ENV/etc/jupyter/nbconfig/notebook.d/
export JUPYCFG=$(jupyter --config-dir)
mkdir -p $JUPYCFG/serverconfig
cp customizations/notebook.json $JUPYCFG/serverconfig/
```

Optional extras:

    rm -f $JUPYCFG/custom/custom.css
    mkdir -p $JUPYCFG/custom
    cp customizations/custom.css $JUPYCFG/custom/

…then restart jupyter

To have the magic available automatically in all notebooks, run:

``` sh
aimagic_install
```

You can check it worked:

``` sh
cat ~/.ipython/profile_default/ipython_config.py
# should print: c.InteractiveShellApp.extensions.append('aimagic')
```

If you want to tweak the look of aimagic uncomment the line that adds
the `custom.css` file to the `custom` subdirectory in your jupyter
config directory.

**NB**: this project requires `nbclassic`, or a notebook version less
than 7. It doesn’t work on Jupyter Lab, vscode, etc.

### Other useful extensions

You might also like to add these extensions:

    pip install nbclassic-collapsible-headings nbclassic-toc2

nbclassic-gist-it has to be installed from a local directory, at least
for now, so cd to your git repo folder and run:

    # First set $GIST_TOKEN or $GITHUB_TOKEN to a github token with access to gist
    git clone git@github.com:AnswerDotAI/nbclassic-gist-it.git
    cd nbclassic-gist-it
    pip install .

## How to use

If you didn’t run `aimagic_install`, then load the extension in your
notebook:

``` python
%load_ext aimagic
```

Then you can start asking the LLM questions. You’ll need the standard
LLM environment vars set up. You can call `%ai` as a *line magic*, which is
what we use for commands that don’t actually call AI, whereas `%%ai`
is used as a cell magic to ask the model a question.

If we `%ai reset`, then a new dialog is created.

## Nifty features

### `%ai` (line magic) commands

| command | description | usage |
|----|----|----|
| obj | return the magic object | `o = %ai obj` |
| dialog | create a markdown cell containing the dialog up to the previous cell | `%ai dialog` |

Put `%ai skip` as the first line of a cell, and that cell will be
skipped when creating Claude’s dialog. Other than that, the cell runs in
the usual way.

### `%%ai` (cell magic) options

These options all also require that you include text on lines underneath
the `%%ai` line.

| option | description | usage |
|----|----|----|
| -t | see the prompt that is created for you. see [below](#trace-prompt) for more info. | `%%ai -t` |
| -nv | don’t include vars in the ai context | `%%ai -nv` |

#### Trace your prompt

Add `-t` after your `%%ai` calls (e.g. `%%aip -t`) to see the trace –
i.e. to see the prompt that is created for you. Or, to see the entire
session exactly as it’s sent to Claude, set this env var:

``` python
import os
os.environ['ANTHROPIC_LOG'] = 'debug'
```

### Keyboard Shortcuts

Here’s a list of keyboard shortcuts you can use to improve your
workflow. If you haven’t done so already follow the steps in the
Customizations section above to setup the keyboard shortcuts.

| name | description | mode | multicell | shortcut |
|----|----|----|----|----|
| disable ai | add a 0 to an ai cell magic which disables the call to the ai | command | yes | `q,d` |
| extract code blocks | extract code blocks from the ai reply (must be used on the reply cell) | command | no | `q,w` |
| skip cell | add `%ai skip` to the top of all selected cells, which removes them from the ai context | command | yes | `q.s` |
| create ai cell magic | prefix the selected cell with %%ai | command | no | `q,1` |

*Note*:

- to make first time setup as easy as possible read the Customization
  section further up in the readme.
- the keyboard shortcut for each command above can be edited in
  `Edit Keyboard Shortcuts`.
- on multicell shortcuts such as skip cell, all cells will be set to the
  desired state of the first selected cell.

##### Troubleshooting

If any of the keyboard shortcuts above are not working, it’s possible
that they are clashing with one of your existing shortcuts. To see if
this is the case:

1.  Go to `Help` in the navbar and open up `Edit Keyboard Shortcuts`.
2.  Confirm that the commands (e.g. disable ai) are listed. They should
    be towards the bottom of the list.
3.  If the commands are listed but no keys are next to `add shortcut`
    then a clash has occurred.
4.  In many cases you can resolve this by scrolling up to the
    `close pager` command and removing its shortcut by clicking `x`.
5.  If you refresh your browser, and check `Edit Keyboard Shortcuts`
    again, the shortcuts for each command should be populated.

