> ## Documentation Index
> Fetch the complete documentation index at: https://docs-code.palyra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Provider Adapters and Configuration

<details>
  <summary>Relevant source files</summary>

  The following files were used as context for generating this wiki page:

  * crates/palyra-cli/src/args/models.rs
  * crates/palyra-cli/src/commands/models.rs
  * crates/palyra-cli/src/commands/operator\_wizard.rs
  * crates/palyra-cli/tests/models\_cli.rs
  * crates/palyra-cli/tests/wizard\_cli.rs
  * crates/palyra-common/src/daemon\_config\_schema.rs
  * crates/palyra-common/src/feature\_rollouts.rs
  * crates/palyra-daemon/src/application/route\_message/response.rs
  * crates/palyra-daemon/src/config/load.rs
  * crates/palyra-daemon/src/config/schema.rs
  * crates/palyra-daemon/src/model\_provider.rs
  * crates/palyra-daemon/src/model\_provider/adapters.rs
  * crates/palyra-daemon/src/openai\_auth.rs
  * crates/palyra-daemon/src/openai\_model\_discovery.rs
  * crates/palyra-daemon/src/openai\_surface.rs
  * crates/palyra-daemon/src/transport/http/handlers/console/auth.rs
  * crates/palyra-daemon/src/transport/http/handlers/console/models.rs
  * crates/palyra-daemon/tests/current\_state\_inventory.rs
  * crates/palyra-daemon/tests/openai\_auth\_surface.rs
  * crates/palyra-daemon/tests/support/mod.rs
  * crates/palyra-model-providers/src/discovery.rs
</details>

The Model Provider subsystem in Palyra handles the abstraction and normalization of interactions with various Large Language Model (LLM) backends. It provides a uniform interface for chat completions, embeddings, and audio transcription while managing complex requirements like streaming event normalization, tool call repair, and multi-layered configuration.

## Provider Adapter Architecture

Palyra uses a trait-based adapter system to support multiple LLM providers. The core runtime traits are `ModelProvider` (for chat and audio) and `EmbeddingsProvider` [crates/palyra-daemon/src/model\_provider.rs#5-12](http://crates/palyra-daemon/src/model_provider.rs#5-12).

### Supported Adapters

* **OpenAI Adapter**: Implements the standard OpenAI chat completions and embeddings protocol [crates/palyra-daemon/src/model\_provider.rs#42-43](http://crates/palyra-daemon/src/model_provider.rs#42-43).
* **Anthropic Adapter**: Supports Claude models via the Messages API and includes specific handling for MiniMax via bearer authentication [crates/palyra-daemon/src/model\_provider.rs#8-9](http://crates/palyra-daemon/src/model_provider.rs#8-9).
* **Google Gemini**: Integrated via the OpenAI-compatible surface [crates/palyra-daemon/src/openai\_surface.rs#61-62](http://crates/palyra-daemon/src/openai_surface.rs#61-62).
* **MiniMax**: Supports both Anthropic-compatible and native OAuth flows [crates/palyra-daemon/src/openai\_surface.rs#48-53](http://crates/palyra-daemon/src/openai_surface.rs#48-53).
* **Deterministic Provider**: A mock provider used for offline testing and fixtures [crates/palyra-daemon/src/model\_provider.rs#7-8](http://crates/palyra-daemon/src/model_provider.rs#7-8).

### Streaming and Normalization

Upstream provider events are normalized into a uniform stream of `ProviderEvent::ModelToken` events [crates/palyra-daemon/src/model\_provider.rs#14-18](http://crates/palyra-daemon/src/model_provider.rs#14-18). This ensures the `Orchestrator` can consume a consistent event format regardless of whether the underlying transport is Server-Sent Events (SSE) or a standard HTTP response body.

### Tool Repair

The subsystem includes a `ToolRepairStreamNormalizer` that monitors assistant output for malformed tool calls [crates/palyra-daemon/src/model\_provider.rs#71-77](http://crates/palyra-daemon/src/model_provider.rs#71-77). It can identify and potentially repair truncated or syntactically incorrect JSON in tool arguments before they reach the execution layer.

### Provider Data Flow

The following diagram illustrates the flow from a high-level request to the specific code entities handling the adapter logic.

**Model Request Normalization Flow**

```mermaid theme={null}
graph TD
    subgraph "Natural Language Space"
        UserRequest["User Prompt & Tools"]
    end

    subgraph "Code Entity Space: crates/palyra-daemon"
        Registry["RegistryBackedModelProvider"]
        AdapterTrait["ProviderChatAdapter (Trait)"]

        subgraph "Adapters"
            OpenAI["OpenAiCompatibleChatAdapter"]
            Anthropic["AnthropicCompatibleChatAdapter"]
        end

        Normalizer["ProviderStreamNormalizer"]
        Repair["ToolRepairStreamNormalizer"]
    end

    UserRequest --> Registry
    Registry --> AdapterTrait
    AdapterTrait --> OpenAI
    AdapterTrait --> Anthropic
    OpenAI --> Normalizer
    Anthropic --> Normalizer
    Normalizer --> Repair
    Repair --> Output["Normalized ProviderEvent Stream"]
```

Sources: [crates/palyra-daemon/src/model\_provider.rs#10-18](http://crates/palyra-daemon/src/model_provider.rs#10-18), [crates/palyra-daemon/src/model\_provider.rs#39-43](http://crates/palyra-daemon/src/model_provider.rs#39-43), [crates/palyra-daemon/src/model\_provider.rs#71-77](http://crates/palyra-daemon/src/model_provider.rs#71-77)

***

## Configuration Pipeline

Palyra employs a multi-layered configuration loading strategy defined in `crates/palyra-daemon/src/config/load.rs`.

### Precedence Layers

1. **Secure Defaults**: Hardcoded values in `DaemonConfig` and related structs [crates/palyra-daemon/src/config/schema.rs#1-13](http://crates/palyra-daemon/src/config/schema.rs#1-13).
2. **TOML Configuration**: Values loaded from `palyra.toml` [crates/palyra-daemon/src/config/load.rs#1-9](http://crates/palyra-daemon/src/config/load.rs#1-9).
3. **Environment Variables**: `PALYRA_*` prefixed variables that override both defaults and file settings [crates/palyra-daemon/src/config/load.rs#4-5](http://crates/palyra-daemon/src/config/load.rs#4-5).

### Secret Management and SecretRefs

Sensitive values like API keys are never stored directly in the primary configuration if a `SecretRef` is provided. The system supports:

* **Inline Secrets**: Stored in the TOML (redacted during exports) [crates/palyra-common/src/daemon\_config\_schema.rs#22-38](http://crates/palyra-common/src/daemon_config_schema.rs#22-38).
* **Vault References**: `VaultRef` points to encrypted storage managed by `palyra-vault` [crates/palyra-daemon/src/model\_provider.rs#19-19](http://crates/palyra-daemon/src/model_provider.rs#19-19).
* **Environment Refs**: Sourcing secrets from specific environment variables at runtime [crates/palyra-daemon/src/config/load.rs#52-52](http://crates/palyra-daemon/src/config/load.rs#52-52).

**Configuration Loading Pipeline**

```mermaid theme={null}
graph LR
    subgraph "Configuration Sources"
        Defaults["Hardcoded Defaults"]
        TOML["palyra.toml"]
        Env["PALYRA_* Env Vars"]
    end

    subgraph "Processing: crates/palyra-daemon/src/config/load.rs"
        Load["load_config()"]
        Parse["parse_root_file_config()"]
        Validate["Cross-field Validation"]
    end

    subgraph "Output"
        Loaded["LoadedConfig (Runtime Types)"]
    end

    Defaults --> Load
    TOML --> Parse
    Parse --> Load
    Env --> Load
    Load --> Validate
    Validate --> Loaded
```

Sources: [crates/palyra-daemon/src/config/load.rs#1-15](http://crates/palyra-daemon/src/config/load.rs#1-15), [crates/palyra-daemon/src/config/load.rs#91-115](http://crates/palyra-daemon/src/config/load.rs#91-115)

***

## CLI and Model Management

The `palyra models` command group provides tools for inspecting and mutating the provider registry.

### Key Commands

| Command           | Function                                              | Code Entity                       |
| :---------------- | :---------------------------------------------------- | :-------------------------------- |
| `status`          | Reports effective model/provider configuration        | `ModelsStatusPayload`             |
| `list`            | Shows available models and provider capabilities      | `ModelsListPayload`               |
| `set`             | Mutates the default chat model with automatic backups | `ModelsMutationPayload`           |
| `test-connection` | Probes provider endpoints with credential validation  | `run_console_provider_probe`      |
| `discover`        | Fetches available models directly from provider APIs  | `console_models_discover_handler` |

Sources: [crates/palyra-cli/src/commands/models.rs#41-68](http://crates/palyra-cli/src/commands/models.rs#41-68), [crates/palyra-cli/src/commands/models.rs#121-128](http://crates/palyra-cli/src/commands/models.rs#121-128), [crates/palyra-daemon/src/transport/http/handlers/console/models.rs#116-137](http://crates/palyra-daemon/src/transport/http/handlers/console/models.rs#116-137)

### Connection Probing and Discovery

The `palyra-daemon` exposes internal handlers for the CLI and Web Console to verify credentials. These probes resolve credentials from the `Vault` or `AuthProfileRegistry` and perform a live request to the provider's `/models` or `/v1/models` endpoint [crates/palyra-daemon/src/transport/http/handlers/console/models.rs#3-9](http://crates/palyra-daemon/src/transport/http/handlers/console/models.rs#3-9).

### Configuration Redaction

To prevent accidental leakage, the `SECRET_CONFIG_PATHS` constant defines all sensitive paths (e.g., `model_provider.openai_api_key`) that must be redacted whenever configuration is exported or displayed in the console [crates/palyra-common/src/daemon\_config\_schema.rs#22-38](http://crates/palyra-common/src/daemon_config_schema.rs#22-38).

Sources: [crates/palyra-common/src/daemon\_config\_schema.rs#22-38](http://crates/palyra-common/src/daemon_config_schema.rs#22-38), [crates/palyra-daemon/src/transport/http/handlers/console/models.rs#145-156](http://crates/palyra-daemon/src/transport/http/handlers/console/models.rs#145-156)