LLM Configuration

Reflexio uses LiteLLM for multi-provider LLM support. You must configure an API key for at least one provider.

API Keys

Method 1: Environment Variables (Recommended)

Set provider-specific environment variables in your .env file. LiteLLM picks them up automatically.

# .env — set one or more provider keys
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=...
DEEPSEEK_API_KEY=...

OpenAI is a common starting point for text generation. Embeddings default to Reflexio's local model unless you override embedding_model_name.

Method 2: Programmatic Configuration

Set API keys via the Config object. Programmatic keys take precedence over environment variables.

from reflexio.models.config_schema import APIKeyConfig, OpenAIConfig

config = client.get_config()
config.api_key_config = APIKeyConfig(
    openai=OpenAIConfig(api_key="sk-your-key-here")
)
client.set_config(config)

curl -X GET "${REFLEXIO_URL:-https://www.reflexio.ai}/api/get_config" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY"

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/set_config" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "...": "updated full config object"
}
JSON

Supported Providers:

For Z.ai models such as zai/glm-5.2, Reflexio uses https://api.z.ai/api/coding/paas/v4 as the built-in API base. Configure only the ZAI_API_KEY; the coding endpoint is a runtime default, not a setting. An explicit per-call API base or a configured custom endpoint still takes precedence.

Custom OpenAI-Compatible Endpoints

Use CustomEndpointConfig to connect to any OpenAI-compatible API. Custom endpoints take priority over other providers for text generation (but not embeddings).

from reflexio.models.config_schema import APIKeyConfig, CustomEndpointConfig

config.api_key_config = APIKeyConfig(
    custom_endpoint=CustomEndpointConfig(
        model="my-model",
        api_key="your-key",
        api_base="http://localhost:8000/v1"
    )
)
client.set_config(config)

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/set_config" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "...": "updated full config object"
}
JSON

Azure OpenAI

Use AzureOpenAIConfig nested inside OpenAIConfig to connect to Azure OpenAI:

from reflexio.models.config_schema import (
    APIKeyConfig, OpenAIConfig, AzureOpenAIConfig
)

config.api_key_config = APIKeyConfig(
    openai=OpenAIConfig(
        azure_config=AzureOpenAIConfig(
            api_key="your-azure-key",
            endpoint="https://your-resource.openai.azure.com/",
            api_version="2024-02-15-preview",
            deployment_name="gpt-4o"
        )
    )
)
client.set_config(config)

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/set_config" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "...": "updated full config object"
}
JSON

Model Selection

Reflexio uses different models for different tasks. Sensible defaults are provided, but you can override them via LLMConfig. Only set fields you want to override — None fields keep the defaults.

Embedding input formatting plus the default retrieval and playbook-clustering thresholds are selected by the exact embedding model:

An explicit request threshold always wins, including 0.0. In hybrid search, the threshold filters only the vector arm; full-text matches remain eligible. An explicit playbook clustering_similarity also wins. Playbook embeddings use only their normalized trigger; they do not fall back to playbook content. This normalization applies when an embedding is computed and does not automatically backfill existing playbook vectors.

from reflexio.models.config_schema import LLMConfig

config = client.get_config()
config.llm_config = LLMConfig(
    generation_model_name="openai/gpt-4o",
    embedding_model_name="text-embedding-3-small",
)
client.set_config(config)

curl -X GET "${REFLEXIO_URL:-https://www.reflexio.ai}/api/get_config" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY"

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/set_config" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "...": "updated full config object"
}
JSON

Model names use LiteLLM's "provider/model-name" format (e.g., "openai/gpt-4o", "anthropic/claude-3-5-sonnet", "deepseek/deepseek-chat").

Z.ai models use Reflexio's prompt-backed structured-output path, and the live-verified zai/glm-5.2 model supports extraction-agent tool loops. Fallback lists may freely mix providers and structured-output strategies — Reflexio walks the primary and fallback models itself, one at a time, and rebuilds the request (structured-output strategy, api_base, per-model timeout) for each one. That means a primary using native JSON Schema can fall back to a prompt-backed provider like Z.ai, and vice versa; no transport compatibility restriction applies to structured-output or text fallback lists.

Changing embedding models puts new query vectors and existing stored vectors in different vector spaces until regeneration finishes, so semantic search quality may be temporarily degraded during the job.

The input-formatting policy is also part of the embedding space. If an existing non-Nomic database was populated by a Reflexio version that added Nomic-style prefixes to every model, rebuild the local SQLite database or run enterprise embedding regeneration after upgrading.