Merge branch 'main' into feature/on_complete_callback

.editorconfig

@@ -0,0 +1,10 @@
+root = true
+
+[*]
+indent_style = tab
+indent_size = 1
+tab_width = 4
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+

README.md

@@ -207,9 +207,9 @@ Voice commands (`:GpWhisper*`) depend on `SoX` (Sound eXchange) to handle audio
 
 ## 5. Configuration
 
-Bellow is a linked snippet with the default values, but I suggest starting with minimal config possible (just `openai_api_key` if you don't have `OPENAI_API_KEY` env set up). Defaults change over time to improve things, options might get deprecated and so on - it's better to change only things where the default doesn't fit your needs.
+Below is a linked snippet with the default values, but I suggest starting with minimal config possible (just `openai_api_key` if you don't have `OPENAI_API_KEY` env set up). Defaults change over time to improve things, options might get deprecated and so on - it's better to change only things where the default doesn't fit your needs.
 
-https://github.com/Robitx/gp.nvim/blob/d90816b2e9185202d72f7b1346b6d33b36350886/lua/gp/config.lua#L8-L355
+https://github.com/Robitx/gp.nvim/blob/3adf3dc7589f54cf7af887879c995aa9846aace5/lua/gp/config.lua#L8-L568
 
 # Usage
 
@@ -311,12 +311,15 @@ Provides custom context per repository:
 
 ## Speech commands
 
-#### `:GpWhisper` <!-- {doc=:GpWhisper}  -->
+#### `:GpWhisper` {lang?} <!-- {doc=:GpWhisper}  -->
 
 Transcription replaces the current line, visual selection or range in the current buffer. Use your mouth to ask a question in a chat buffer instead of writing it by hand, dictate some comments for the code, notes or even your next novel..
 
 For the rest of the whisper commands, the transcription is used as an editable prompt for the equivalent non whisper command - `GpWhisperRewrite` dictates instructions for `GpRewrite` etc.
 
+You can override the default language by setting {lang} with the 2 letter
+shortname of your language (e.g. "en" for English, "fr" for French etc).
+
 #### `:GpWhisperRewrite` <!-- {doc=:GpWhisperRewrite}  -->
 
 Similar to `:GpRewrite`, but the prompt instruction dialog uses transcribed spoken instructions.
@@ -463,7 +466,7 @@ Ahoy there!
 
 # Shortcuts
 
-There are no default global shortcuts to mess with your own config. Bellow are examples for you to adjust or just use directly.
+There are no default global shortcuts to mess with your own config. Below are examples for you to adjust or just use directly.
 
 ## Native
 
@@ -731,7 +734,7 @@ Here are some more examples:
           .. "```{{filetype}}\n{{selection}}\n```\n\n"
           .. "Please respond by writing table driven unit tests for the code above."
       local agent = gp.get_command_agent()
-      gp.Prompt(params, gp.Target.enew, nil, agent.model, template, agent.system_prompt)
+      gp.Prompt(params, gp.Target.vnew, agent, template)
   end,
   ````
 
@@ -744,7 +747,7 @@ Here are some more examples:
           .. "```{{filetype}}\n{{selection}}\n```\n\n"
           .. "Please respond by explaining the code above."
       local agent = gp.get_chat_agent()
-      gp.Prompt(params, gp.Target.popup, nil, agent.model, template, agent.system_prompt)
+      gp.Prompt(params, gp.Target.popup, agent, template)
   end,
   ````
 
@@ -757,7 +760,7 @@ Here are some more examples:
           .. "```{{filetype}}\n{{selection}}\n```\n\n"
           .. "Please analyze for code smells and suggest improvements."
       local agent = gp.get_chat_agent()
-      gp.Prompt(params, gp.Target.enew("markdown"), nil, agent.model, template, agent.system_prompt)
+      gp.Prompt(params, gp.Target.enew("markdown"), agent, template)
   end,
   ````
 
@@ -766,9 +769,12 @@ Here are some more examples:
   ```lua
   -- example of adding command which opens new chat dedicated for translation
   Translator = function(gp, params)
-    local agent = gp.get_command_agent()
-  local chat_system_prompt = "You are a Translator, please translate between English and Chinese."
-  gp.cmd.ChatNew(params, agent.model, chat_system_prompt)
+      local chat_system_prompt = "You are a Translator, please translate between English and Chinese."
+      gp.cmd.ChatNew(params, chat_system_prompt)
+
+      -- -- you can also create a chat with a specific fixed agent like this:
+      -- local agent = gp.get_chat_agent("ChatGPT4o")
+      -- gp.cmd.ChatNew(params, chat_system_prompt, agent)
   end,
   ```
 
@@ -783,7 +789,16 @@ Here are some more examples:
   end,
   ```
 
-The raw plugin text editing method `Prompt` has seven aprameters:
+The raw plugin text editing method `Prompt` has following signature:
+```lua
+---@param params table  # vim command parameters such as range, args, etc.
+---@param target integer | function | table  # where to put the response
+---@param agent table  # obtained from get_command_agent or get_chat_agent
+---@param template string  # template with model instructions
+---@param prompt string | nil  # nil for non interactive commads
+---@param whisper string | nil  # predefined input (e.g. obtained from Whisper)
+Prompt(params, target, agent, template, prompt, whisper)
+```
 
 - `params` is a [table passed to neovim user commands](https://neovim.io/doc/user/lua-guide.html#lua-guide-commands-create), `Prompt` currently uses:
 
@@ -868,25 +883,29 @@ The raw plugin text editing method `Prompt` has seven aprameters:
   }
   ```
 
-- `prompt`
-  - string used similarly as bash/zsh prompt in terminal, when plugin asks for user command to gpt.
-  - if `nil`, user is not asked to provide input (for specific predefined commands - document this, explain that, write tests ..)
-  - simple `🤖 ~ ` might be used or you could use different msg to convey info about the method which is called  
-    (`🤖 rewrite ~`, `🤖 popup ~`, `🤖 enew ~`, `🤖 inline ~`, etc.)
-- `model`
-  - see [gpt model overview](https://platform.openai.com/docs/models/overview)
+
+- `agent` table obtainable via `get_command_agent` and `get_chat_agent` methods which have following signature:
+  ```lua
+  ---@param name string | nil
+  ---@return table # { cmd_prefix, name, model, system_prompt, provider }
+  get_command_agent(name)
+  ```
+
 - `template`
 
   - template of the user message send to gpt
-  - string can include variables bellow:
+  - string can include variables below:
 
     | name            | Description                       |
     | --------------- | --------------------------------- |
     | `{{filetype}}`  | filetype of the current buffer    |
     | `{{selection}}` | last or currently selected text   |
     | `{{command}}`   | instructions provided by the user |
 
-- `system_template`
-  - See [gpt api intro](https://platform.openai.com/docs/guides/chat/introduction)
+- `prompt`
+  - string used similarly as bash/zsh prompt in terminal, when plugin asks for user command to gpt.
+  - if `nil`, user is not asked to provide input (for specific predefined commands - document this, explain that, write tests ..)
+  - simple `🤖 ~ ` might be used or you could use different msg to convey info about the method which is called  
+    (`🤖 rewrite ~`, `🤖 popup ~`, `🤖 enew ~`, `🤖 inline ~`, etc.)
 - `whisper`
   - optional string serving as a default for input prompt (for example generated from speech by Whisper)

doc/gp.nvim.txt

@@ -1,4 +1,4 @@
-*gp.nvim.txt*             For NVIM v0.8.0            Last change: 2024 July 09
+*gp.nvim.txt*             For NVIM v0.8.0            Last change: 2024 July 17
 
 ==============================================================================
 Table of Contents                                  *gp.nvim-table-of-contents*
@@ -245,14 +245,14 @@ recording and processing:
 
 5. CONFIGURATION                                    *gp.nvim-5.-configuration*
 
-Bellow is a linked snippet with the default values, but I suggest starting with
+Below is a linked snippet with the default values, but I suggest starting with
 minimal config possible (just `openai_api_key` if you don’t have
 `OPENAI_API_KEY` env set up). Defaults change over time to improve things,
 options might get deprecated and so on - it’s better to change only things
 where the default doesn’t fit your needs.
 
 
-https://github.com/Robitx/gp.nvim/blob/d90816b2e9185202d72f7b1346b6d33b36350886/lua/gp/config.lua#L8-L355
+https://github.com/Robitx/gp.nvim/blob/3adf3dc7589f54cf7af887879c995aa9846aace5/lua/gp/config.lua#L8-L568
 
 
 ==============================================================================
@@ -396,7 +396,7 @@ Provides custom context per repository:
 SPEECH COMMANDS                                      *gp.nvim-speech-commands*
 
 
-:GpWhisper                                                        *:GpWhisper*
+:GpWhisper {lang?}                                                *:GpWhisper*
 
 Transcription replaces the current line, visual selection or range in the
 current buffer. Use your mouth to ask a question in a chat buffer instead of
@@ -407,6 +407,9 @@ For the rest of the whisper commands, the transcription is used as an editable
 prompt for the equivalent non whisper command - `GpWhisperRewrite` dictates
 instructions for `GpRewrite` etc.
 
+You can override the default language by setting {lang} with the 2 letter
+shortname of your language (e.g. "en" for English, "fr" for French etc).
+
 
 :GpWhisperRewrite                                          *:GpWhisperRewrite*
 
@@ -601,7 +604,7 @@ resulting `test` file:
 ==============================================================================
 4. Shortcuts                                               *gp.nvim-shortcuts*
 
-There are no default global shortcuts to mess with your own config. Bellow are
+There are no default global shortcuts to mess with your own config. Below are
 examples for you to adjust or just use directly.
 
 
@@ -876,7 +879,7 @@ Here are some more examples:
                 .. "```{{filetype}}\n{{selection}}\n```\n\n"
                 .. "Please respond by writing table driven unit tests for the code above."
             local agent = gp.get_command_agent()
-            gp.Prompt(params, gp.Target.enew, nil, agent.model, template, agent.system_prompt)
+            gp.Prompt(params, gp.Target.vnew, agent, template)
         end,
     <
 - `:GpExplain`
@@ -887,7 +890,7 @@ Here are some more examples:
                 .. "```{{filetype}}\n{{selection}}\n```\n\n"
                 .. "Please respond by explaining the code above."
             local agent = gp.get_chat_agent()
-            gp.Prompt(params, gp.Target.popup, nil, agent.model, template, agent.system_prompt)
+            gp.Prompt(params, gp.Target.popup, agent, template)
         end,
     <
 - `:GpCodeReview`
@@ -898,16 +901,19 @@ Here are some more examples:
                 .. "```{{filetype}}\n{{selection}}\n```\n\n"
                 .. "Please analyze for code smells and suggest improvements."
             local agent = gp.get_chat_agent()
-            gp.Prompt(params, gp.Target.enew("markdown"), nil, agent.model, template, agent.system_prompt)
+            gp.Prompt(params, gp.Target.enew("markdown"), agent, template)
         end,
     <
 - `:GpTranslator`
     >lua
         -- example of adding command which opens new chat dedicated for translation
         Translator = function(gp, params)
-          local agent = gp.get_command_agent()
-        local chat_system_prompt = "You are a Translator, please translate between English and Chinese."
-        gp.cmd.ChatNew(params, agent.model, chat_system_prompt)
+            local chat_system_prompt = "You are a Translator, please translate between English and Chinese."
+            gp.cmd.ChatNew(params, chat_system_prompt)
+
+            -- -- you can also create a chat with a specific fixed agent like this:
+            -- local agent = gp.get_chat_agent("ChatGPT4o")
+            -- gp.cmd.ChatNew(params, chat_system_prompt, agent)
         end,
     <
 - `:GpBufferChatNew`
@@ -920,7 +926,17 @@ Here are some more examples:
         end,
     <
 
-The raw plugin text editing method `Prompt` has seven aprameters:
+The raw plugin text editing method `Prompt` has following signature:
+
+>lua
+    ---@param params table  # vim command parameters such as range, args, etc.
+    ---@param target integer | function | table  # where to put the response
+    ---@param agent table  # obtained from get_command_agent or get_chat_agent
+    ---@param template string  # template with model instructions
+    ---@param prompt string | nil  # nil for non interactive commads
+    ---@param whisper string | nil  # predefined input (e.g. obtained from Whisper)
+    Prompt(params, target, agent, template, prompt, whisper)
+<
 
 - `params` is a |table passed to neovim user commands|, `Prompt` currently uses:
     - `range, line1, line2` to work with |ranges|
@@ -999,23 +1015,26 @@ The raw plugin text editing method `Prompt` has seven aprameters:
             end,
         }
     <
-- `prompt`
-    - string used similarly as bash/zsh prompt in terminal, when plugin asks for user command to gpt.
-    - if `nil`, user is not asked to provide input (for specific predefined commands - document this, explain that, write tests ..)
-    - simple `🤖 ~` might be used or you could use different msg to convey info about the method which is called
-        (`🤖 rewrite ~`, `🤖 popup ~`, `🤖 enew ~`, `🤖 inline ~`, etc.)
-- `model`
-    - see gpt model overview <https://platform.openai.com/docs/models/overview>
+- `agent` table obtainable via `get_command_agent` and `get_chat_agent` methods
+    which have following signature:
+    >lua
+        ---@param name string | nil
+        ---@return table # { cmd_prefix, name, model, system_prompt, provider }
+        get_command_agent(name)
+    <
 - `template`
     - template of the user message send to gpt
-    - string can include variables bellow:
+    - string can include variables below:
           name            Description
           --------------- -----------------------------------
           {{filetype}}    filetype of the current buffer
           {{selection}}   last or currently selected text
           {{command}}     instructions provided by the user
-- `system_template`
-    - See gpt api intro <https://platform.openai.com/docs/guides/chat/introduction>
+- `prompt`
+    - string used similarly as bash/zsh prompt in terminal, when plugin asks for user command to gpt.
+    - if `nil`, user is not asked to provide input (for specific predefined commands - document this, explain that, write tests ..)
+    - simple `🤖 ~` might be used or you could use different msg to convey info about the method which is called
+        (`🤖 rewrite ~`, `🤖 popup ~`, `🤖 enew ~`, `🤖 inline ~`, etc.)
 - `whisper`
     - optional string serving as a default for input prompt (for example generated from speech by Whisper)