Merge pull request #4 from gopher-lab/docs/inference-basilica-pr

Docs: inference providers, Basilica, and screenshots

Author: teslashibe

docs/docs/guides/configuration.md

@@ -67,6 +67,54 @@ Use OpenAI directly:
 2. Paste in the **OpenAI API Key** field
 3. Click **Test** to verify
 
+### Inference
+
+Gopher resolves inference settings per loop, which means the main evolution loop, tools, backtests,
+Monte Carlo validation, and compression can each use different providers or models when needed.
+
+**Inference providers:**
+- **Gopher Credits**
+- **OpenRouter**
+- **OpenAI**
+- **Ollama (local)**
+- **Basilica (OpenAI-compatible)**
+- **Custom (OpenAI-compatible)**
+
+**Per-loop overrides:**
+You can set overrides per loop (provider, model ID, base URL, API key) in the desktop app:
+**Settings → Advanced → Inference Overrides**.
+
+**Base URL conventions:**
+- Use the OpenAI-compatible **root** URL only (no `/chat/completions`).
+- When using Gopher Credits, the base URL is normalized to `.../api/v1/gopher`.
+
+**Environment variables:**
+- `BART_GOPHER_CODE`
+- `BART_GOPHER_API_URL`
+- `OPENROUTER_API_KEY`
+- `OPENAI_API_KEY`
+
+#### Basilica (OpenAI-compatible)
+
+Basilica deployments expose an OpenAI-compatible API. See:
+- https://docs.basilica.ai/introduction
+- https://docs.basilica.ai/inference
+
+Setup steps:
+1. Deploy a model with Basilica (vLLM or SGLang) and copy the deployment URL.
+2. Configure Gopher with:
+   - **Base URL**: `${DEPLOYMENT_URL}/v1`
+   - **API Key**: `not-needed` (Basilica handles auth for the deployment URL)
+3. Example model IDs (Hugging Face IDs):
+   - `Qwen/Qwen2.5-7B-Instruct`
+   - `meta-llama/Llama-3.1-8B-Instruct`
+   - `mistralai/Mistral-7B-Instruct-v0.3`
+   - `deepseek-ai/DeepSeek-V2-Chat`
+
+![Settings - General](/img/screenshots/desktop/03-settings-general.png)
+
+![Settings - Advanced (Inference Overrides)](/img/screenshots/desktop/06-settings-advanced.png)
+
 ## Model Settings
 
 ### Loop Model

docs/docs/guides/quickstart.md

@@ -34,6 +34,7 @@ Use your own API key from a provider:
 |----------|-------------|---------|
 | **OpenRouter** | Access to 100+ models | [openrouter.ai/keys](https://openrouter.ai/keys) |
 | **OpenAI** | GPT-4, GPT-4o models | [platform.openai.com/api-keys](https://platform.openai.com/api-keys) |
+| **Basilica** | OpenAI-compatible deployment URL | [docs.basilica.ai](https://docs.basilica.ai/inference) |
 
 **Gopher Credits** are recommended for simplicity - inference is handled automatically with optimized models.
 
@@ -47,9 +48,16 @@ Use your own API key from a provider:
    - **For Gopher Credits**: Paste your Gopher Key in the **Gopher Key** field
    - **For OpenRouter**: Paste in the **OpenRouter API Key** field
    - **For OpenAI**: Paste in the **OpenAI API Key** field
+   - **For Basilica**: Add a custom model with base URL `${DEPLOYMENT_URL}/v1` and API key `not-needed`
 4. Click **Test** to verify the connection
 5. A green checkmark indicates success
 
+Advanced users can set per-loop inference overrides in **Settings → Advanced → Inference Overrides**.
+
+![Main dashboard](/img/screenshots/desktop/01-main-dashboard.png)
+
+![Settings - General](/img/screenshots/desktop/03-settings-general.png)
+
 ### CLI
 
 Run the interactive setup wizard:

docs/docs/guides/troubleshooting.md

@@ -94,6 +94,29 @@ Gopher Keys require the Gopher inference API (`gotrader.gopher-ai.com`), not Ope
 
 The `--base-url` flag only applies to non-Gopher keys. Gopher keys always use the Gopher API.
 
+### "Base URL must not include /chat/completions"
+
+Gopher expects OpenAI-compatible **root** URLs only. If you include `/chat/completions`, requests will fail.
+
+**Solution:**
+- Use the root URL (e.g., `https://api.openai.com/v1`).
+- For custom providers, remove `/chat/completions` and keep the base at `/v1`.
+
+### "Gopher API origin override not working"
+
+If you override the Gopher API origin, it must be the **origin only** (no `/chat/completions`).
+
+**Solution:**
+- Set `BART_GOPHER_API_URL` to the API origin (e.g., `https://gotrader.gopher-ai.com`).
+- Restart the app/CLI after changing env vars.
+
+### "Test model fails but inference runs"
+
+The **Test** button validates the selected provider with the resolved inference settings:
+- **Gopher Credits**: Ensure your Gopher Key is set and valid.
+- **OpenRouter/OpenAI/Custom**: Ensure the provider key is set for that provider.
+- **Per-loop overrides**: If you set a per-loop override with a different provider, that provider’s key must be configured.
+
 ### "Rate limit exceeded"
 
 You've made too many API requests in a short period.

docs/docs/reference/models.md

@@ -14,6 +14,7 @@ Gopher supports multiple LLM providers and models for strategy generation and ba
 | **OpenRouter** | Access 100+ models with one key | Yes |
 | **OpenAI** | GPT-4, GPT-4o models | Yes |
 | **Ollama** | Local models | No |
+| **Basilica** | OpenAI-compatible deployments | No (deployment URL) |
 | **Custom** | Any OpenAI-compatible API | Varies |
 
 ## Gopher Credits (Recommended)
@@ -161,9 +162,14 @@ Add any OpenAI-compatible API endpoint.
    - **Model ID**: The model identifier
    - **Display Name**: Friendly name
    - **Provider**: Select "Custom"
-   - **Base URL**: API endpoint (e.g., `https://api.example.com/v1`)
+   - **Base URL**: OpenAI-compatible root URL only (e.g., `https://api.example.com/v1`)
    - **API Key**: Your key for this endpoint
 
+Note: Do not include `/chat/completions` in the base URL. For per-loop overrides, see
+[Configuration → Inference](/guides/configuration#inference).
+
+![Settings - Models](/img/screenshots/desktop/04-settings-models.png)
+
 ### Compatible Services
 
 Many services offer OpenAI-compatible APIs:
@@ -172,6 +178,7 @@ Many services offer OpenAI-compatible APIs:
 - **Anyscale**: [anyscale.com](https://anyscale.com)
 - **Perplexity**: [perplexity.ai](https://perplexity.ai)
 - **Groq**: [groq.com](https://groq.com)
+- **Basilica**: [docs.basilica.ai](https://docs.basilica.ai/inference)
 - **Local LLMs**: LM Studio, vLLM, text-generation-webui
 
 ## Model Selection Tips