feat(models): Implement model visibility management with hidden models configuration

docs/installation/configuration.md

@@ -0,0 +1,154 @@
+# Configuration Guide
+
+This guide covers all the configuration options available in Perplexica's `config.toml` file.
+
+## Configuration File Structure
+
+Perplexica uses a TOML configuration file to manage settings. Copy `sample.config.toml` to `config.toml` and modify it according to your needs.
+
+```bash
+cp sample.config.toml config.toml
+```
+
+## Configuration Sections
+
+### [GENERAL]
+
+General application settings.
+
+#### SIMILARITY_MEASURE
+- **Type**: String
+- **Options**: `"cosine"` or `"dot"`
+- **Default**: `"cosine"`
+- **Description**: The similarity measure used for embedding comparisons in search results ranking.
+
+#### KEEP_ALIVE
+- **Type**: String
+- **Default**: `"5m"`
+- **Description**: How long to keep Ollama models loaded into memory. Use time suffixes like `"5m"` for 5 minutes, `"1h"` for 1 hour, or `"-1m"` for indefinite.
+
+#### BASE_URL
+- **Type**: String
+- **Default**: `""` (empty)
+- **Description**: Optional base URL override. When set, overrides the detected URL for OpenSearch and other public URLs.
+
+#### HIDDEN_MODELS
+- **Type**: Array of Strings
+- **Default**: `[]` (empty array)
+- **Description**: Array of model names to hide from the user interface and API responses. Hidden models will not appear in model selection lists but can still be used if directly specified.
+- **Example**: `["gpt-4", "claude-3-opus", "expensive-model"]`
+- **Use Cases**:
+  - Hide expensive models to prevent accidental usage
+  - Remove models that don't work well with your configuration
+  - Simplify the UI by hiding unused models
+
+### [MODELS]
+
+Model provider configurations. Each provider has its own subsection.
+
+#### [MODELS.OPENAI]
+- **API_KEY**: Your OpenAI API key
+
+#### [MODELS.GROQ]
+- **API_KEY**: Your Groq API key
+
+#### [MODELS.ANTHROPIC]
+- **API_KEY**: Your Anthropic API key
+
+#### [MODELS.GEMINI]
+- **API_KEY**: Your Google Gemini API key
+
+#### [MODELS.CUSTOM_OPENAI]
+Configuration for OpenAI-compatible APIs (like LMStudio, vLLM, etc.)
+- **API_KEY**: API key for the custom endpoint
+- **API_URL**: Base URL for the OpenAI-compatible API
+- **MODEL_NAME**: Name of the model to use
+
+#### [MODELS.OLLAMA]
+- **API_URL**: Ollama server URL (e.g., `"http://host.docker.internal:11434"`)
+
+#### [MODELS.DEEPSEEK]
+- **API_KEY**: Your DeepSeek API key
+
+#### [MODELS.LM_STUDIO]
+- **API_URL**: LM Studio server URL (e.g., `"http://host.docker.internal:1234"`)
+
+### [API_ENDPOINTS]
+
+External service endpoints.
+
+#### SEARXNG
+- **Type**: String
+- **Description**: SearxNG API URL for web search functionality
+- **Example**: `"http://localhost:32768"`
+
+## Environment Variables
+
+Some configurations can also be set via environment variables, which take precedence over the config file:
+
+- `OPENAI_API_KEY`
+- `GROQ_API_KEY`
+- `ANTHROPIC_API_KEY`
+- `GEMINI_API_KEY`
+- And others following the pattern `{PROVIDER}_API_KEY`
+
+## Model Visibility Management
+
+The `HIDDEN_MODELS` setting allows server administrators to control which models are visible to users:
+
+### How It Works
+1. Models listed in `HIDDEN_MODELS` are filtered out of API responses
+2. The settings UI shows all models (including hidden ones) for management
+3. Hidden models can still be used if explicitly specified in API calls
+
+### Managing Hidden Models
+1. **Via Configuration File**: Edit the `HIDDEN_MODELS` array in `config.toml`
+2. **Via Settings UI**: Use the "Model Visibility" section in the settings page
+3. **Via API**: Use the `/api/config` endpoint to update the configuration
+
+### API Behavior
+- **Default**: `/api/models` returns only visible models
+- **Include Hidden**: `/api/models?include_hidden=true` returns all models (for admin use)
+
+## Security Considerations
+
+- Store API keys securely and never commit them to version control
+- Use environment variables for sensitive configuration in production
+- Regularly rotate API keys
+- Consider using `HIDDEN_MODELS` to prevent access to expensive or sensitive models
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Models not appearing**: Check if they're listed in `HIDDEN_MODELS`
+2. **API errors**: Verify API keys and URLs are correct
+3. **Ollama connection issues**: Ensure the Ollama server is running and accessible
+4. **SearxNG not working**: Verify the SearxNG endpoint is correct and accessible
+
+### Configuration Validation
+
+The application validates configuration on startup and will log errors for:
+- Invalid TOML syntax
+- Missing required fields
+- Invalid URLs or API endpoints
+- Unreachable services
+
+## Example Configuration
+
+```toml
+[GENERAL]
+SIMILARITY_MEASURE = "cosine"
+KEEP_ALIVE = "5m"
+BASE_URL = ""
+HIDDEN_MODELS = ["gpt-4", "claude-3-opus"]
+
+[MODELS.OPENAI]
+API_KEY = "sk-your-openai-key-here"
+
+[MODELS.OLLAMA]
+API_URL = "http://localhost:11434"
+
+[API_ENDPOINTS]
+SEARXNG = "http://localhost:32768"
+```