Quantasia Provider Configuration Guide
This document explains how to define AI providers using the [[providers]] TOML schema
Quantasia supports multiple AI backends through a flexible provider system.
Each provider is defined using a [[providers]] block in your TOML configuration file.
This guide explains every field, how providers work, and how sysops should configure them.


1. Overview of Providers
A provider represents a backend service that Quantasia can send AI requests to.

Examples include:
     OpenAI (cloud) 
     Ollama (cloud) 
     Ollama-Local (your own LAN or localhost instance) 
     LMStudio-Local (your own LAN or localhost instance)

Each provider entry defines:
     The providers name (name)
     The API endpoint (url)
     The environment variable used for authentication (api_environment_variable)
     The API key (optional if using environment variables)  (api_key)
     The URL used to pull a list of available models (pull_list_url)

Quantasia can support multiple providers [[providers]] tags at once, and each [[services]] tag entry in the config.toml file
references one of these [[providers]] tags by name.


2. Provider Naming Rules
The name field must begin with either:
     OpenAI 
     Ollama 
     LMStudio

This allows Quantasia to automatically determine:
     Whether the provider is cloud-based or local 
     Which API conventions to use 
     How to format requests 


Examples of valid names:
     OpenAI 
     OpenAI-Local 
     Ollama 
     Ollama-Local 
     Ollama-Cloud 
     LMStudio
     LMStudio-Local


3. Provider Fields Explained
Below is a breakdown of every field in a [[providers]] block.


name
The providers identifier.
Must begin with OpenAI , Ollama or LMStudio.
This is the value referenced by each [[services]] entry.


url
The API endpoint used for sending chat requests.
Examples:
     OpenAI cloud:
https://api.openai.com/v1/chat/completions
     Ollama cloud:
https://ollama.com/api/chat
     Ollama-Local:
http://localhost:11434/api/chat
or
http://<LAN-IP>:11434/api/chat
     LMStudio-Local
     http://<LAN-IP>:1234/api/v1/chat


api_environment_variable
The name of the environment variable that stores the API key.
Examples:
     OPENAI_API_KEY 
     OLLAMA_API_KEY 
     LM_API_TOKEN
    If you prefer not to store keys in the config file, set this in your OS environment and leave api_key blank.


api_key
The API key used to authenticate with the provider.

You may:
     Put the key directly here 
     OR leave it blank and use the environment variable defined in your OS instead 
For local Ollama instances, this is usually empty.


pull_list_url
The URL used to retrieve a list of available models from the provider.
Examples:
     OpenAI:
https://api.openai.com/v1/models
     Ollama cloud:
https://api.ollama.com/api/tags
     Ollama-Local:
http://<LAN-IP>:11434/api/tags
     LMStudio-Local:
http://<LAN-IP>:1234/api/v1/models
Note: Quantasia uses these to populate the Sysop Service Editors model list.


4. Example Providers (From Your File)
Below is a documentation-ready explanation of each provider you included.

Provider 1: OpenAI (Cloud)

[[providers]]
name = "OpenAI"
url = "https://api.openai.com/v1/chat/completions"
api_environment_variable = "OPENAI_API_KEY"
api_key = "sk-"
pull_list_url = "https://api.openai.com/v1/models"

Purpose:
Connects Quantasia to OpenAIs cloud models (GPT-4.1, GPT-4o, etc.).
Notes:
     Requires a valid OpenAI API key 
     Supports the full OpenAI model list 
     Ideal for high-quality reasoning and creative tasks 


Provider 2: Ollama (Cloud)

[[providers]]
name = "Ollama"
url = "https://ollama.com/api/chat"
api_environment_variable = "OLLAMA_API_KEY"
api_key = "544bed"
pull_list_url = "https://api.ollama.com/api/tags"

Purpose:
Connects to Ollamas cloud-hosted models.
Notes:
     Requires an Ollama cloud API key 
     Provides access to cloud-optimized versions of popular models 
     Good for sysops who want Ollamas ecosystem without hosting locally 


Provider 3: Ollama-Local (LAN or Localhost)

[[providers]]
name = "Ollama-Local"
url = "http://192.168.50.99:11434/api/chat"
api_environment_variable = ""
api_key = ""
pull_list_url = "http://192.168.50.99:11434/api/tags"

Purpose:
Connects Quantasia to a local Ollama instance running on your LAN or the same machine.
Notes:
     No API key required 
     Fastest and cheapest option 
     Perfect for offline boards or sysops who want full control 
     Make sure the IP and port match your Ollama host 


Provider 4: LMStudio-Local (LAN or Localhost)

[[providers]]
name = "LMStudio-Local"
url = "http://192.168.50.99:1234/api/v1/chat"
api_environment_variable = ""
api_key = ""
pull_list_url = "http://192.168.50.99:1234/api/v1/models"

Purpose:
Connects Quantasia to a local Ollama instance running on your LAN or the same machine.
Notes:
     No API key required 
     Fastest and cheapest option 
     Perfect for offline boards or sysops who want full control 
     Make sure the IP and port match your Ollama host 


5. Best Practices for Sysops
Use environment variables for cloud keys. Keeps your config file clean and secure.

Name providers clearly
Examples:
     OpenAI 
     OpenAI-Local 
     Ollama 
     Ollama-Local 
     LMStudio-Local

Use local models for speed
Local models respond faster and cost nothing.
Use cloud providers for quality
Cloud models offer the highest reasoning and creativity.
Keep unused providers disabled or removed
This keeps your config tidy and reduces confusion.


6. Troubleshooting
Models not appearing in the Sysop Editor
     Check pull_list_url 
     Ensure API key is valid 
     Ensure provider name matches the [[services]] provider field 

Requests failing
     Verify the url 
     Check network connectivity 
     Ensure the provider supports the token_parameter _name your [[services]] instance is using 

Local Ollama / LM Studio not responding
     Confirm the IP and port 
     Ensure Ollama / LM Studio service is running 
     Confirm the service is not binding to the localhost address (127.0.0.1) but instead is binding to 0.0.0.0 so it can be accessed from another machine on the network
     Check firewall rules 



