467 lines
16 KiB
Plaintext
467 lines
16 KiB
Plaintext
*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 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://platform.openai.com/signup
|
|
2. Any model that uses the OpenAI API. See |neural-provider-openai.url|
|
|
|
|
To select the tool that Neural will use, set |g:neural.providers| to the
|
|
appropriate value. OpenAI is the default data provider.
|
|
|
|
===============================================================================
|
|
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
|
|
providers 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 provider 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 provider 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 = {
|
|
\ 'providers': [
|
|
\ {
|
|
\ 'openai': {
|
|
\ 'api_key': $OPENAI_API_KEY,
|
|
\ },
|
|
\ },
|
|
\ ],
|
|
\}
|
|
<
|
|
In a Neovim `init.lua` call `require('neural').setup`: >
|
|
|
|
require('neural').setup({
|
|
ui = {
|
|
animated_sign_enabled = false,
|
|
},
|
|
providers = {
|
|
{
|
|
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.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.
|
|
|
|
g:neural.providers *g:neural.providres*
|
|
*vim.g.neural.providers*
|
|
Type: |List|
|
|
Default: `[]`
|
|
|
|
The List of providers to configure which providers Neural will use.
|
|
|
|
NOTE: At the moment Neural will only ever use the first provider, and
|
|
ignore the rest. If unspecified, OpenAI will be used by default.
|
|
|
|
|
|
-------------------------------------------------------------------------------
|
|
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. This settings should be set
|
|
as an Dictionary/table in the `providers` List with `type` set to `'openai'`.
|
|
|
|
|
|
api_key *neural-provider-openai.api_key*
|
|
|
|
Type: |String|
|
|
Default: `''`
|
|
|
|
The OpenAI API key. See: https://beta.openai.com/signup/
|
|
|
|
|
|
frequency_penalty
|
|
*neural-provider-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
|
|
|
|
|
|
max_tokens *neural-provider-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`).
|
|
|
|
|
|
model *neural-provider-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
|
|
|
|
See |neural-provider-openai.use_chat_api| if changing models, as you may
|
|
need to use the chat API only for newer models.
|
|
|
|
|
|
presence_penalty
|
|
*neural-provider-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
|
|
|
|
|
|
temperature *neural-provider-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.
|
|
|
|
|
|
top_p *neural-provider-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.
|
|
|
|
|
|
use_chat_api *neural-provider-openai.use_chat_api*
|
|
Type: |Boolean|
|
|
Default: `true`
|
|
|
|
For configuring if Neural should use `/v1/chat/completions` if `true`, or
|
|
the `/v1/completions` API if `false`. Older models such as
|
|
`'gpt-3.5-turbo-instruct'` will only run with the completions API, and
|
|
newer models may only run with the chat API.
|
|
|
|
|
|
url *neural-provider-openai.url*
|
|
Type: |String|
|
|
Default: `'https://api.openai.com'`
|
|
|
|
For configuring the API URL to send LLM requests to. This URL can be
|
|
configured to connect Neural to other models with OpenAI compatible APIs
|
|
such as DeepSeek, Qwen, etc.
|
|
|
|
|
|
-------------------------------------------------------------------------------
|
|
4.4 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 = {
|
|
\ 'providers': [
|
|
\ {
|
|
\ '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:
|