<!-- source: https://deepwiki.com/qhkm/zeptoclaw/10-llm-provider-integration -->

# LLM Provider Integration

- src/kernel/provider.rs
- src/providers/mod.rs
- src/providers/registry.rs

This document covers the architecture and integration of LLM (Large Language Model) providers in ZeptoClaw. It describes the provider abstraction layer, registry system, credential resolution, and how providers are instantiated and used throughout the system.

For specific provider configuration details, see [Provider Configuration](/qhkm/zeptoclaw/10.1-provider-configuration). For decorator patterns (retry/fallback/quota), see [Provider Decorators](/qhkm/zeptoclaw/10.3-provider-decorators). For runtime model switching, see [Runtime Model Switching](/qhkm/zeptoclaw/10.4-runtime-model-switching).

## Purpose and Scope

The LLM provider integration system provides:

- A unified LLMProvider trait for interacting with different LLM APIs src/providers/mod.rs 3-5 src/providers/types.rs 1-50
- A static registry ( PROVIDER_REGISTRY ) mapping 18+ providers to runtime implementations src/providers/registry.rs 55-196
- Three primary backend routing paths ( anthropic , openai , and vertex ) src/providers/registry.rs 21 src/kernel/provider.rs 43-129
- Credential resolution with support for API keys, OAuth tokens (Google/Gemini), and Application Default Credentials (ADC) src/providers/registry.rs 42-43 src/kernel/provider.rs 68-75
- Provider decorators for retry logic, fallback chains, and quota enforcement src/providers/mod.rs 66-80
- Runtime model switching for per-chat model overrides src/kernel/provider.rs 145-165

This page focuses on the core provider abstraction and integration points. Provider-specific implementation details are covered in subsection [Supported Providers](/qhkm/zeptoclaw/10.2-supported-providers).

Sources: [src/providers/mod.rs1-84](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/mod.rs#L1-L84) [src/providers/registry.rs1-196](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/registry.rs#L1-L196) [src/kernel/provider.rs1-130](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/provider.rs#L1-L130)

## Architecture Overview

### LLMProvider Trait and Backend Routing

The following diagram illustrates how the abstract `LLMProvider` trait connects to specific backend implementations and decorator wrappers.

**Diagram: Provider Trait to Code Entity Mapping**

```

```

**Backend Routing Strategy**

The provider system uses specific backend types in the `ProviderSpec` to determine how to instantiate the runtime client [src/providers/registry.rs21](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/registry.rs#L21-L21)

Sources: [src/providers/registry.rs10-196](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/registry.rs#L10-L196) [src/kernel/provider.rs39-130](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/provider.rs#L39-L130)

## Provider Registry

### Static Registry Structure

The `PROVIDER_REGISTRY` defines metadata for all supported providers in priority order.

**Diagram: Configuration to Runtime Selection Flow**

```

```

**Registry Priority Order**

Providers are resolved based on their position in the registry [src/providers/registry.rs55-196](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/registry.rs#L55-L196) Key providers include:

1. anthropic - Native Claude API src/providers/registry.rs 56-65
2. openai - Native OpenAI API src/providers/registry.rs 66-75
3. openrouter - Multi-provider proxy src/providers/registry.rs 77-85
4. gemini - Native Google Gemini REST API with thinking model support src/providers/registry.rs 117-125 src/kernel/provider.rs 59-76
5. vertex - Google Cloud Vertex AI src/providers/registry.rs 127-135
6. azure - Azure OpenAI (requires custom auth header api-key ) src/providers/registry.rs 177-186

Sources: [src/providers/registry.rs55-196](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/registry.rs#L55-L196) [src/providers/mod.rs41-59](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/mod.rs#L41-L59)

## Authentication and Credential Resolution

ZeptoClaw handles diverse authentication schemes, including API keys, OAuth tokens, and cloud-native identity.

**Credential Resolution Priority** [src/kernel/provider.rs59-76](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/provider.rs#L59-L76)

The `refresh_oauth_credentials_if_needed` function is called during the provider chain build to ensure tokens are valid [src/kernel/provider.rs26](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/provider.rs#L26-L26)

Sources: [src/providers/registry.rs42-43](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/registry.rs#L42-L43) [src/kernel/provider.rs23-30](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/provider.rs#L23-L30) [src/kernel/provider.rs59-115](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/provider.rs#L59-L115)

## Core Types

### LLMProvider Trait

The core interface for all models [src/providers/types.rs1-50](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/types.rs#L1-L50):

```

```

### Provider Chain Assembly

The `build_provider_chain` function assembles the final execution stack [src/kernel/provider.rs23-30](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/provider.rs#L23-L30):

1. Resolution : resolve_runtime_providers finds valid providers in the config src/kernel/provider.rs 154
2. Instantiation : provider_from_runtime_selection maps backends to structs src/kernel/provider.rs 39-42
3. Decoration : apply_quota_wrapper and apply_retry_wrapper wrap the base provider src/kernel/provider.rs 160-161 src/kernel/provider.rs 28
4. Fallback : If multiple providers are configured, they are wrapped in a FallbackProvider src/kernel/provider.rs 180-186

Sources: [src/kernel/provider.rs1-190](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/provider.rs#L1-L190) [src/providers/mod.rs60-84](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/mod.rs#L60-L84)

## Error Classification

The `parse_provider_error` function centralizes error handling by mapping HTTP status codes and response bodies to structured `ProviderError` variants [src/providers/mod.rs92-124](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/mod.rs#L92-L124)

Sources: [src/providers/mod.rs88-124](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/mod.rs#L88-L124) [src/providers/error_classifier.rs1-65](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/error_classifier.rs#L1-L65)

## Next Steps

- Provider Configuration — Detailed coverage of PROVIDER_REGISTRY and authentication methods.
- Supported Providers — Detailed implementation details for Anthropic, OpenAI, Gemini, Vertex, etc.
- Provider Decorators — Documentation for RetryProvider , FallbackProvider , and QuotaProvider .
- Runtime Model Switching — Deep dive into per-chat model overrides.
- Error Classification — Detailed mapping of error messages to retryable status.
- Provider Plugins — Using ProviderPlugin for external LLM integrations via JSON-RPC 2.0.
- Cost Tracking and Quotas — Usage metrics and budget enforcement details.
