Improve local model configuration and documentation

Author: w0rp

README.md

@@ -4,7 +4,8 @@
 
 A Neovim/Vim coding agent plugin. Neural integrates various machine learning
 tools so you can let AI write code for you in Neovim/Vim, among other helpful
-things. Use OpenAI's APIs made famous with ChatGPT, in Vim.
+things. Use OpenAI's APIs made famous with ChatGPT, in Vim, or other local
+models.
 
 ## 🌟 Features
 
@@ -20,8 +21,7 @@ Experience lightning-fast code generation and completion with asynchronous
 streaming.
 
 Edit any kind of text document. It can be used to generate Python docstrings,
-fix comments spelling/grammar mistakes, generate ideas and much more. See
-[examples from OpenAI](https://beta.openai.com/examples) for a start.
+fix comments spelling/grammar mistakes, generate ideas and much more.
 
 ## 🔌 Plugin Integrations
 
@@ -82,8 +82,21 @@ interact with. OpenAI is Neural's default data provider, and one of the easiest
 to configure.
 
 You will need to obtain an [OpenAI API key](https://beta.openai.com/signup/).
-Once you have your key, configure Neural to use that key, whether in a Vim
-script or in a Lua config.
+Once you have your key, configure Neural to use that key, whether in a Lua
+config or in Vimscript.
+
+```lua
+-- Configure Neural like so in Lua
+require('neural').setup({
+    providers = {
+        {
+            openai = {
+                api_key = vim.env.OPENAI_API_KEY,
+            },
+        },
+    },
+})
+```
 
 ```vim
 " Configure Neural like so in Vimscript
@@ -98,22 +111,38 @@ let g:neural = {
 \}
 ```
 
+Try typing `:Neural say hello`, and if all goes well the machine learning
+tool will say "hello" to you in the current buffer. Type `:help neural` to
+see the full documentation.
+
+You can configure the `url` for an OpenAI provider to run Neural with local
+models or other servers that offer an OpenAI compatible API, for example:
+
 ```lua
 -- Configure Neural like so in Lua
 require('neural').setup({
     providers = {
         {
             openai = {
-                api_key = vim.env.OPENAI_API_KEY,
+                url = 'http://localhost:7860',
             },
         },
     },
 })
 ```
 
-Try typing `:Neural say hello`, and if all goes well the machine learning
-tool will say "hello" to you in the current buffer. Type `:help neural` to
-see the full documentation.
+```vim
+" Configure Neural like so in Vimscript
+let g:neural = {
+\   'providers': [
+\       {
+\           'openai': {
+\               'url': 'http://localhost:7860',
+\           },
+\       },
+\   ],
+\}
+```
 
 ## 🛠️ Commands
 

doc/neural.txt

@@ -367,6 +367,15 @@ use_chat_api                              *neural-provider-openai.use_chat_api*
   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*
 

src/neural/provider/openai.py

@@ -47,8 +47,11 @@ def get_openai_completion(
 ) -> None:
     headers = {
         "Content-Type": "application/json",
-        "Authorization": f"Bearer {config.api_key}",
     }
+
+    if config.api_key:
+        headers["Authorization"] = f"Bearer {config.api_key}"
+
     data: dict[str, Any] = {
         "model": config.model,
         "temperature": config.temperature,
@@ -137,8 +140,8 @@ def load_config(raw_config: dict[str, Any]) -> Config:
 
     api_key = raw_config.get('api_key')
 
-    if not isinstance(api_key, str) or not api_key:  # type: ignore
-        raise ValueError("api_key is not defined")
+    if not isinstance(api_key, str | None):  # type: ignore
+        raise ValueError(f"api_key is an invalid type: {type(api_key)}")
 
     model = raw_config.get('model')
 
@@ -191,7 +194,7 @@ def load_config(raw_config: dict[str, Any]) -> Config:
 
     return Config(
         url=url,
-        api_key=api_key,
+        api_key=api_key or '',
         model=model,
         use_chat_api=use_chat_api,
         temperature=temperature,

test/python/provider/test_openai.py

@@ -11,9 +11,13 @@
 from neural.provider import openai
 
 
-def get_valid_config(model: str = "foo") -> dict[str, Any]:
+def get_valid_config(
+    model: str = "foo",
+    *,
+    api_key: str = '.',
+) -> dict[str, str | int]:
     return {
-        "api_key": ".",
+        "api_key": api_key,
         "model": model,
         "prompt": "say hello",
         "temperature": 1,
@@ -35,8 +39,7 @@ def test_load_config_errors() -> None:
     for modification, expected_error in [
         ({"url": 1}, "url must be a string"),
         ({"url": "x"}, "url must start with http(s)://"),
-        ({"url": "https://x", "api_key": ""}, "api_key is not defined"),
-        ({"api_key": "."}, "model is not defined"),
+        ({"url": "https://x"}, "model is not defined"),
         ({"model": ""}, "model is not defined"),
         (
             {"model": "x", "use_chat_api": 1},
@@ -126,6 +129,41 @@ def test_main_function_rate_other_error() -> None:
             openai.main()
 
 
+@pytest.mark.parametrize(['api_key', 'expected_headers'], [
+    pytest.param(
+        'sk-fake',
+        {
+            'Authorization': 'Bearer sk-fake',
+            'Content-type': 'application/json',
+        },
+        id='authenticated',
+    ),
+    pytest.param(
+        '',
+        {'Content-type': 'application/json'},
+        id='unauthenticated',
+    ),
+])
+def test_openai_authentication(
+    api_key: str,
+    expected_headers: dict[str, str],
+) -> None:
+    result_data = b'data: [DONE]\n\n'
+
+    with mock.patch.object(sys.stdin, 'readline') as readline_mock, \
+        mock.patch.object(urllib.request, 'urlopen') as urlopen_mock:
+
+        urlopen_mock.return_value.__enter__.return_value = BytesIO(result_data)
+
+        readline_mock.return_value = json.dumps({
+            "config": get_valid_config(api_key=api_key),
+            "prompt": "hello there",
+        })
+        openai.main()
+
+        assert urlopen_mock.mock_calls[0][1][0].headers == expected_headers
+
+
 def test_print_openai_completion_results() -> None:
     result_data = (
         b'data: {"id": "cmpl-6jMlRJtbYTGrNwE6Lxy1Ns1EtD0is", "object": "text_completion", "created": 1676270285, "choices": [{"text": "\\n", "index": 0, "logprobs": null, "finish_reason": null}], "model": "gpt-3.5-turbo-instruct"}\n'  # noqa