doc/askgpt.txt

*askgpt.txt*	Ask ChatGPT anything in you Vim.
                                                                  *AskGPT.vim*

------------------------------------------------------------------------------
INTRODUCTION                                             *askgpt-introduction*

This plugin provides you a chat companion similar to the ChatGPT web interface,
rather than typical AI plugin for text completion.
You can start a conversation by typing |:AskGPT| and ask anything!

Here are some ideas you can use this plugin:

  * Ask about your code, the meaning of a function, or for usage examples.

  * Get help to improve your document, proofread it, or changing its tone.

  * Translate a document or code into another language.

  * Ask to do tasks like doing a calculation, or format markdown table.

  * Or just for a casual chat, of course!

------------------------------------------------------------------------------
INSTALL                                                       *askgpt-install*

1. Install askgpt.vim plugin using your favorite plugin manager.

2. Add settings to your vimrc.
>
	" OpenAI API key.
	let g:askgpt_api_key = 'xxxxxxxxxxxxxxxx'

	" (Optional) Path to curl command.
	let g:askgpt_curl_command = ['curl']

3. Start vim and try |:AskGPT|.

------------------------------------------------------------------------------
COMMANDS                                                     *askgpt-commands*

:[range]AskGPT [{message}]                                           *:AskGPT*
	Open or focus a chat window.

	The {message} will be sent as your message in the chat window, And
	ChatGPT will answer to it.

	If [range] provided, the contents in the range will be shared with
	ChatGPT to ask about content.

	For example, to ask about your code, select function in |Visual| mode
	and execute like:
>
	:'<,'>AskGPT what is this function?
<
	To translate whole document, execute like:
>
	:%AskGPT translate it to English
>

:[range]AskGPT! [{message}]                                         *:AskGPT!*
	Open a new chat window.

	This command always opens a new chat buffer, while |:AskGPT| focus an
	existing buffer if one already exists.

:AskGPTCancel                                                  *:AskGPTCancel*
	Cancel to generate message.

:AskGPTRetry                                                    *:AskGPTRetry*
	Generate last AI message again.

------------------------------------------------------------------------------
OPTIONS                                                       *askgpt-options*

AI behavior:
  |g:askgpt_api_key|
  |g:askgpt_max_characters|
  |g:askgpt_max_letters|
  |g:askgpt_model|
  |g:askgpt_temperature|
  |g:askgpt_top_p|
  |g:askgpt_prompt|

UI preference:
  |g:askgpt_file_name|
  |g:askgpt_use_default_maps|

Environment setting:
  |g:askgpt_curl_command|


AI behavior~

*g:askgpt_api_key*
	Type: |String|

	An OpenAI API key.
	You can get one from https://platform.openai.com/.

*g:askgpt_max_characters*
	Type: |Number|
	Default: 10000

	The maximum characters count of history to provide to ChatGPT.
	The number includes your messages, AI's messages, and codes that you
	shared via |:AskGPT| command.

	To make it larger provides more information to AI, but it consumes a
	lot of tokens that you have to pay for them.
	To make it smaller provides less information, and it costs less.

	The default value 10000 is aimed for English and some source codes.
	However, this is very depends on what you ask and what AI responses.
	1000 is usually too large to non-English languages or complex codes.
	It is recommended to optimise to your usage.

	0 means unlimited.

	seealso: |g:askgpt_max_messages|

*g:askgpt_max_messages*
	Type: |Number|
	Default: 10

	The maximum number of messages in history to provide to ChatGPT.
	The number includes your messages, AI's messages, and codes that you
	shared via |:AskGPT| command.

	This option is similar to |g:askgpt_max_characters| but it limits the
	number of messages.

	0 means unlimited.

	Please see also: |g:askgpt_max_characters|

*g:askgpt_model*
	Type: |String|
	Default: gpt-3.5-turbo

	The model name to use, for example, `gpt-3.5-turbo` or `gpt-4`.

	Please see the latest model list on the OpenAI's document:
	https://platform.openai.com/docs/models/model-endpoint-compatibility

*g:askgpt_temperature*
	Type: |Float|
	Default: 1.0

	The temperature parameter of the OpenAI API, between 0 to 2.

	Setting a lower value makes predictable responses, and higher value
	makes more random responses.

	Detail:
	https://platform.openai.com/docs/api-reference/chat/create#chat/create-temperature

*g:askgpt_top_p*
	Type: |Float|
	Default: 1.0

	The top_p parameter for the OpenAI API, between 0 to 1.

	This value is similar to |g:askgpt_temperature|.
	Setting lower value let AI to choose more likely words, and higher
	value allows AI to choose less likely words.

	Detail:
	https://platform.openai.com/docs/api-reference/chat/create#chat/create-top_p

*g:askgpt_prompt*
	Type: |String|
	Default:
	    You are AskGPT.vim, an AI conversation assistant.
	    Answer very concisely and clearly.

	    Chat syntax: markdown
	    File types user is editing: {filetypes}

	The prompt that is always provided to the AI, to let AI know who it is
	and how it should response.

	Some markers are replaced with context-specific values before provide
	to the AI.

	{filetypes} is replaced by file types that user is currently editing.

	{date} is replaced by the current date in YYYY-mm-dd format

	{weekday} is replaced by the day of week in local language.
	You can check this value by `:echo strftime('%A')`.

	{time} is replaced by the current time in HH:MM format.


UI preference~

*g:askgpt_file_name*
	Type: |String|
	Default: askgpt-%Y%m%dT%H%M%S.md

	Default file name for a chat buffer.
	This value will be passed to |strftime()| before use as a buffer name.

*g:askgpt_use_default_maps*
	Type: |Boolean|
	Default: v:true

	Use default key mappings in a chat buffer.
	Please see also |askgpt-mappings|.


Environment setting~

*g:askgpt_curl_command*
	Type: |List| of |String|s
	Default: ["curl"]

	Command to execute curl.

	For example, you can give extra options to the curl such as --proxy: >
		let g:askgpt_curl_command = [
			\ "curl",
			\ "--proxy", "http://example.com",
			\ ]

------------------------------------------------------------------------------
Mappings                                                     *askgpt-mappings*

There are some default mappings for a chat buffer.

  <Return>  |<Plug>(askgpt-submit)|
  [[        |<Plug>(askgpt-go-prev-message)|
  ]]        |<Plug>(askgpt-go-next-message)|

To disable these and set your own mappings, use |g:askgpt_use_default_maps|.
For Example, to use <C-J> to submitting message: >
	let g:askgpt_use_default_maps = v:false
	augroup askgpt
	    autocmd BufRead askgpt://
		    \ imap <buffer> <C-J> <Plug>(askgpt-submit) |
		    \ nmap <buffer> <C-J> <Plug>(askgpt-submit)
	augroup END
<

*<Plug>(askgpt-submit)*                                      *askgpt_<Return>*
	Default mapping: <Return>

	Submit a message to the AI and get a response.

	This only works on the last __User__ line of a chat buffer and below.
	Otherwise, this shortcut does nothing.

*<Plug>(askgpt-go-prev-message)*                                   *askgpt_[[*
*<Plug>(askgpt-go-next-message)*                                   *askgpt_]]*
	Default mapping: [[ / ]]

	Jump to the previous / next message in the chat buffer.

------------------------------------------------------------------------------
vim:tw=78:isk=!-~,^*,^\|,^\":ts=8:noet:ft=help:norl: