*neural.txt* Plugin to generate text and code with machine learning.
*neural*

===============================================================================
CONTENTS                                                      *neural-contents*

  1. Introduction ............................... |neural-introduction|
  2. Supported Tools ............................ |neural-support|
  3. Commands/Keybinds .......................... |neural-commands|
  4. Options .................................... |neural-options|
    4.1 UI ........................................ |neural-ui|
    4.2 Neural Buffer ............................. |neural-buffer|
    4.3 OpenAI .................................... |neural-openai|
    4.4 ChatGPT ................................... |neural-chatgpt|
    4.5 Highlights ................................ |neural-highlights|
  5. API ........................................ |neural-api|
  6. Environment Variables ...................... |neural-env|
    6.1 Linux + KDE ............................. |neural-env-kde|
  7. Contact .................................... |neural-contact|

===============================================================================
1. Introduction                                           *neural-introduction*

Neural is a plugin for Vim and Neovim that provides blazingly fast AI code
generation, editing, and completion.

It uses machine learning tools under the hood, such as OpenAI's GPT-3 API, to
generate text, code, and much more.

===============================================================================
2. Supported Languages & Tools                                 *neural-support*

Neural supports the following tools.

1. OpenAI - https://beta.openai.com/signup/

To select the tool that Neural will use, set |g:neural.selected| to the
appropriate value. OpenAI is the default data source.

===============================================================================
3. Commands/Keybinds                                          *neural-commands*


`:Neural`                                                              *Neural*

  Prompt Neural for a response. e.g. `:Neural say hello`

  If the command is run with no text input and `nui.vim` is installed, a fancy
  UI for entering the prompt will be shown.

  See https://github.com/MunifTanjim/nui.nvim for installation instructions.

  A plug mapping `<Plug>(neural_prompt)` is defined for this command.

  A |NeuralWritePost| event will be fired whenever Neural successfully
  completes writing text to a buffer.


`:NeuralBuffer`                                                  *NeuralBuffer*

  Create a buffer with a `neuralbuf` filetype for interacting with neural
  sources directly. This can be a useful scratch buffer and playground for code
  generation and completion.

  - See |neural-buffer| for configuration options.
  - See |NeuralCompletion| for running neural completions in the buffer.

  A plug mapping `<Plug>(neural_buffer)` is defined for this.


`:NeuralCompletion`                                          *NeuralCompletion*

  A command for a |NeuralBuffer| (`neuralbuf` filetype) that sends all buffer
  contents to the current neural source for completion and appends the
  response to the buffer.

  A `neuralbuf` plug mapping `<Plug>(neural_completion)` is defined for this
  with the default: `<C-CR>`


`:NeuralExplain`                                                *NeuralExplain*

  A |visual-mode| command for explaining the highlighted lines. The visual
  selection will be sent to the currently selected source model and the
  response will be displayed in a preview window.

  Neural will make basic attempts to redact lines that appear to contain
  passwords or secrets.

  A plug mapping `<Plug>(neural_explain)` is defined for this.


`:NeuralStop`                                                      *NeuralStop*

  Stop any currently running Neural tasks, and immediately stop printing text
  to a Vim buffer at the first available opportunity.

  A plug mapping `<Plug>(neural_stop)` is defined for this.

  Neural will by default bind <C-c> (CTRL-C) to stopping neural if no mapping
  is already defined for that key. This behavior can be disabled by setting
  |g:neural.set_default_keybinds| to any falsy value.


`:NeuralViewPrompt`                                          *NeuralViewPrompt*

  View the complete prompt that will be sent. e.g. `:NeuralViewPrompt say hello`

  Neural will automatically alter prompts sent to virtual assistants before
  they are sent depending on the filetype of the current file and the
  surrounding context. This command allows you to see what that prompt will be
  before it is sent.

  A plug mapping `<Plug>(neural_view_prompt)` is defined for this.


===============================================================================
4. Options                                                     *neural-options*
                                                                     *g:neural*

All of Neural's options are controlled with a single dictionary that can be
configured either in Vim or in Lua.

In Vim just set `g:neural`: >

  let g:neural = {
  \   'source': {
  \       'openai': {
  \           'api_key': $OPENAI_API_KEY,
  \       },
  \   },
  \}
<
In a Neovim `init.lua` call `require('neural').setup`: >

  require('neural').setup({
      ui = {
          animated_sign_enabled = false,
      },
      source = {
          openai = {
              api_key = vim.env.OPENAI_API_KEY,
          },
      },
  })
<

You can modify settings at any time, before or after Neural is loaded, and
Neural will react to the change in settings. A complete list of supported
options listed below.

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

g:neural.selected                                           *g:neural.selected*
                                                        *vim.g.neural.selected*
  Type: |String|
  Default: `'openai'`

  Selects a source for Neural to use. Possible values are:

  1. `'openai'` - OpenAI
  2. `'chatgpt'` - ChatGPT


g:neural.set_default_keybinds                   *g:neural.set_default_keybinds*
                                            *vim.g.neural.set_default_keybinds*
  Type: |Boolean|
  Default: `v:true`

  Sets default keybinds for Neural, assuming the keys are not already bound
  to something else. The default keybinds are as follows: >

  nnoremap <C-c> <Plug>(neural_stop)
<

g:neural.pre_process.enabled                     *g:neural.pre_process.enabled*
                                             *vim.g.neural.pre_process.enabled*
  Type: |Boolean|
  Default: `v:true`

  If `v:true`, pre-process prompts before sending them to language models.

  Neural edits the text you send automatically by default to improve the
  quality of prompts to produce better results for each filetype.


-------------------------------------------------------------------------------
4.1 UI                                                              *neural-ui*

Options for configuring various UI configurations are listed below.

g:neural.ui.echo_enabled                             *g:neural.ui.echo_enabled*
                                                 *vim.g.neural.ui.echo_enabled*
  Type: |Boolean|
  Default: `v:true`

  If `v:true`, echo messages about things that are happening.

  You might want to disable this option if you are asked to press Enter a lot.


g:neural.ui.prompt_enabled                         *g:neural.ui.prompt_enabled*
                                               *vim.g.neural.ui.prompt_enabled*
  Type: |Boolean|
  Default: `v:true`

  If `v:true`, show a fancy prompt.

  Available in Neovim only with `nui.nvim` installed.

  The icon can be changed with |g:neural.ui.prompt_icon|.


g:neural.ui.prompt_icon                               *g:neural.ui.prompt_icon*
                                                  *vim.g.neural.ui.prompt_icon*
  Type: |String|
  Default: `'🗲'`

  Set the icon Neural uses in the Neovim animated prompt.

  See also: |g:neural.ui.prompt_enabled|.


g:neural.ui.animated_sign_enabled           *g:neural.ui.animated_sign_enabled*
                                        *vim.g.neural.ui.animated_sign_enabled*
  Type: |Boolean|
  Default: `v:true`

  If `v:true`, show animated signs when Neural is working.

  Available in Neovim only with `significant.nvim` installed.


-------------------------------------------------------------------------------
4.2 Neural Buffer                                               *neural-buffer*

Options for configuring the |NeuralBuffer| are listed below.


g:neural.buffer.completion_key                 *g:neural.buffer.completion_key*
                                           *vim.g.neural.buffer.completion_key*
  Type: |String|
  Default: `'<C-CR>'`

  The default key mapping for creating a Neural Buffer.



g:neural.buffer.create_mode                       *g:neural.buffer.create_mode*
                                              *vim.g.neural.buffer.create_mode*
  Type: |String|
  Default: `'vertical'`

  Options between `'vertical'` or `'horizontal'`.
  The split mode when creating a new Neural Buffer.


g:neural.buffer.wrap                                     *g:neural.buffer.wrap*
                                                     *vim.g.neural.buffer.wrap*
  Type: |Boolean|
  Default: `v:true`

  Option to wrap the contents of the Neural Buffer.


-------------------------------------------------------------------------------
4.3 OpenAI                                                      *neural-openai*

Options for configuring OpenAI are listed below.


g:neural.source.openai.api_key                 *g:neural.source.openai.api_key*
                                           *vim.g.neural.source.openai.api_key*
  Type: |String|
  Default: `''`

  The OpenAI API key. See: https://beta.openai.com/signup/


g:neural.source.openai.frequency_penalty
                                     *g:neural.source.openai.frequency_penalty*
                                 *vim.g.neural.source.openai.frequency_penalty*
  Type: |Number| or |Float|
  Default: `0.1`

  Number between `-2.0` and `2.0`.
  Positive values penalize new tokens based on their existing frequency in the
  output so far, decreasing the likelihood to repeat the same line verbatim.

  See: https://platform.openai.com/docs/api-reference/parameter-details


g:neural.source.openai.max_tokens           *g:neural.source.openai.max_tokens*
                                        *vim.g.neural.source.openai.max_tokens*
  Type: |Number|
  Default: `1024`

  The maximum number of tokens to generate in the output.
  One token generally corresponds to `~4` characters for common English text.

  This translates to roughly `¾` of a word (e.g. `100 tokens ~= 75 words`).


g:neural.source.openai.model                     *g:neural.source.openai.model*
                                             *vim.g.neural.source.openai.model*
  Type: |String|
  Default: `'gpt-3.5-turbo-instruct'`

  The model to use for OpenAI. Please consult OpenAI's documentation for more
  information on models: https://platform.openai.com/docs/models/overview


g:neural.source.openai.presence_penalty
                                      *g:neural.source.openai.presence_penalty*
                                  *vim.g.neural.source.openai.presence_penalty*
  Type: |Number| or |Float|
  Default: `0.1`

  Number between `-2.0` and `2.0`.

  Positive values penalize new tokens based on whether they appear in the text
  so far, increasing the model's likelihood to talk about new topics.

  See: https://platform.openai.com/docs/api-reference/parameter-details


g:neural.source.openai.temperature         *g:neural.source.openai.temperature*
                                       *vim.g.neural.source.openai.temperature*
  Type: |Number| or |Float|
  Default: `0.2`

  The OpenAI sampling temperature between `0` and `2`.

  Higher values like `0.8` will make the output more random, while lower values
  like `0.2` will make it more focused and deterministic.


g:neural.source.openai.top_p                     *g:neural.source.openai.top_p*
                                             *vim.g.neural.source.openai.top_p*
  Type: |Number| or |Float|
  Default: `1`

  The OpenAI nucleus sampling between `0` and `1`.

  An alternative to sampling with temperature, called nucleus sampling, where
  the model considers the results of the tokens with top_p probability mass.

  For example `0.1` means only tokens comprising the top `10%` probability mass
  are considered.

  OpenAI recommends altering this or temperature but not both.


-------------------------------------------------------------------------------
4.4 ChatGPT                                                    *neural-chatgpt*

Options for configuring ChatGPT are listed below.

Many options are simliar to OpenAI completion options above.


g:neural.source.chatgpt.api_key               *g:neural.source.chatgpt.api_key*
                                          *vim.g.neural.source.chatgpt.api_key*
  Type: |String|
  Default: `''`

  The OpenAI API key. See: https://beta.openai.com/signup/


g:neural.source.chatgpt.frequency_penalty
                                    *g:neural.source.chatgpt.frequency_penalty*
                                *vim.g.neural.source.chatgpt.frequency_penalty*
  Type: |Number| or |Float|
  Default: `0.1`

  See Also: |g:neural.source.openai.frequency_penalty|


g:neural.source.chatgpt.max_tokens         *g:neural.source.chatgpt.max_tokens*
                                       *vim.g.neural.source.chatgpt.max_tokens*
  Type: |Number|
  Default: `2048`

  See Also: |g:neural.source.openai.max_tokens|


g:neural.source.chatgpt.model                   *g:neural.source.chatgpt.model*
                                            *vim.g.neural.source.chatgpt.model*
  Type: |String|
  Default: `'gpt-3.5-turbo'`

  The model to use for ChatGPT. Please consult OpenAI's documentation for more
  information on models: https://platform.openai.com/docs/models/overview


g:neural.source.chatgpt.presence_penalty
                                     *g:neural.source.chatgpt.presence_penalty*
                                 *vim.g.neural.source.chatgpt.presence_penalty*
  Type: |Number| or |Float|
  Default: `0.1`

  See Also: |g:neural.source.openai.presence_penalty|


g:neural.source.chatgpt.temperature       *g:neural.source.chatgpt.temperature*
                                      *vim.g.neural.source.chatgpt.temperature*
  Type: |Number| or |Float|
  Default: `0.2`

  See Also: |g:neural.source.openai.temperature|


g:neural.source.chatgpt.top_p                   *g:neural.source.chatgpt.top_p*
                                            *vim.g.neural.source.chatgpt.top_p*
  Type: |Number| or |Float|
  Default: `1`

  See Also: |g:neural.source.openai.top_p|


-------------------------------------------------------------------------------
4.5 Highlights                                              *neural-highlights*

The following highlights can be configured to change |neural|'s colors.


`NeuralPromptBorder`                                       *NeuralPromptBorder*

  Default: `ctermfg=172 guifg=#ff9d0a`

  Color for the |Neural| prompt border.

===============================================================================
5. API                                                             *neural-api*

NeuralWritePost                                       *NeuralWritePost-autocmd*
                                                              *NeuralWritePost*

  An event that fires whenever Neural successfully completes writing text to a
  buffer. This event can be used to trigger other commands on files, such as
  automatically fixing generated code with ALE. >

  augroup NeuralEvents
      autocmd!
      autocmd User NeuralWritePost ALEFix!
  augroup END
<

===============================================================================
6. Environment Variables                                           *neural-env*

Configuring environment variables across different operating systems is almost
a research topic of its own. This section of documentation provides some
helpful pointers for where you might like to stuff environment variables on
different systems. Pick the strategy you like most, based on a balance of your
own level of security concerns and need for convenience.


-------------------------------------------------------------------------------
6.1 Linux + KDE                                                *neural-env-kde*

KDE makes it easy to set environment variables such that they can be read by
all GUI applications. One strategy you can try is to make environment
variables available to GUI apps, and then also expose them in your shell.  KDE
will read any script stored in `~/.config/plasma-workspace/env`. Create a file
named `~/.config/plasma-workspace/env/keys.sh` with the following contents,
and make sure to set `chmod ug+x` on the file. >

  #!/bin/bash

  # Put whatever variables you want here.
  export OPENAI_API_KEY='sh...'
<
Once in place, `source` the same script in your shell startup script, such as
`~/.bashrc`, like so: >

  # shellcheck source=.config/plasma-workspace/env/keys.sh
  source ~/.config/plasma-workspace/env/keys.sh
<
The `shellcheck` comment will tell `shellcheck` where to read the script from,
which will help it to understand which variables are valid, etc. After logging
out and in again, you will be able to access your environment variables in any
Vim or GUI Vim startup script you like uniformly, like so: >

  let g:neural = {
  \   'source': {
  \       'openai': {
  \           'api_key': $OPENAI_API_KEY,
  \       },
  \   },
  \}
<
All applications on your system will also be able to read the same environment
variable, so consider that in terms of security.


===============================================================================
7. Contact                                                     *neural-contact*

If you like this plugin, and wish to get in touch, check out the GitHub
page for issues and more at https://github.com/dense-analysis/neural

Machines should work; people should think.

===============================================================================
  vim:tw=78:ts=2:sts=2:sw=2:ft=help:norl:
