Expand description
§paladin-llm
LLM provider adapters for the Paladin framework.
This crate provides concrete adapter implementations for multiple LLM providers,
all implementing the paladin_ports::output::llm_port::LlmPort trait defined
in paladin-ports.
§Supported Providers
| Feature flag | Provider | Types |
|---|---|---|
openai (default) | OpenAI | openai::OpenAIAdapter, openai::OpenAIConfig |
anthropic | Anthropic | anthropic::AnthropicAdapter, anthropic::AnthropicConfig |
deepseek | DeepSeek | deepseek::DeepSeekAdapter, deepseek::DeepSeekConfig |
kimi | Kimi (Moonshot AI) | kimi::KimiAdapter, kimi::KimiConfig |
qwen | Qwen (Alibaba DashScope) | qwen::QwenAdapter, qwen::QwenConfig |
grok | Grok (xAI) | grok::GrokAdapter, grok::GrokConfig |
ollama | Ollama (self-hosted, keyless) | ollama::OllamaAdapter, ollama::OllamaConfig |
openai-compatible | Any OpenAI-compatible endpoint (operator-configured) | openai_compatible::OpenAiCompatibleAdapter, openai_compatible::OpenAiCompatibleConfig |
gemini | Google Gemini (text-only, bespoke protocol) | gemini::GeminiAdapter, gemini::GeminiConfig |
mock (default) | Testing | mock::MockLlmAdapter, mock::MultiStepMockLlmPort |
| (none — always compiled) | Model fallback chain over any of the above | fallback::FallbackLlmAdapter |
openai-embeddings | OpenAI Embeddings | openai::OpenAIEmbeddingAdapter |
vision | Vision (multimodal) | Extends OpenAI and Anthropic adapters |
§Architecture
Follows the Hexagonal Architecture pattern — this crate is a pure adapter
layer. It depends only on paladin-core (domain types) and paladin-ports
(port trait contracts). It has no dependency on the root paladin crate.
§Quick Start
use paladin_llm::openai::{OpenAIAdapter, OpenAIConfig};
use paladin_llm::provider_factory::LlmProviderFactory;
// From environment variables
let factory = LlmProviderFactory::new();
let provider = factory.create("openai").expect("OPENAI_API_KEY must be set");Modules§
- cadence
- Rate pacing (PACE-02, D-01/D-07/D-08):
cadence::CadenceLlmAdapterdecorates anArc<dyn LlmPort>with a per-(provider, model) gate that a provider 429 opens, over the sharedpaladin_ports::output::cadence_port::CadencePort. Not feature-gated – it needs no provider adapter itself, mirroringpricingandfallback. Cadence decorator –CadenceLlmAdapter(PACE-02, D-01, D-07, D-08; Phase 43) - config
- Shared configuration types for LLM providers and request behavior. Per-domain configuration types for the paladin-llm crate.
- error
- Error types returned by provider adapters.
- fallback
- Model fallback (FT-FR-16/17):
fallback::FallbackLlmAdaptercomposes an ordered chain of plainLlmPorts and hops on Transient/Unknown errors only. Not feature-gated (ADR-0046) — it needs no provider adapter itself. - http_
status - The one shared HTTP-status-to-
LlmErrormapping every provider adapter routes its non-2xx branch through (FT-FR-01, D-03) — redacts before it bounds, and emits a typedProviderError { status }for every status without a dedicated variant. Not feature-gated. One shared HTTP-status-to-LlmErrormapping for every provider adapter in this crate (Doc 04 FT-FR-01, Phase 25 D-03). - llm_
analysis_ service - LLM-backed content analysis service orchestration.
- mock
- Mock provider adapters for tests and deterministic workflows. Mock LLM adapters for testing.
- openai
- OpenAI provider adapter and related configuration. OpenAI LLM adapter module.
- pricing
- Treasurer per-call pricing (D-08/D-09, ADR-0052):
pricing::PricingLlmAdapterdecorates anArc<dyn LlmPort>with cost from an operatorpaladin_core::platform::container::cost::PriceTable. Not feature-gated — it needs no provider adapter itself, mirroringfallback. Pricing decorator —PricingLlmAdapter(D-08, D-09; ADR-0052) - provider_
factory - Factory for selecting provider adapters from runtime configuration.
- rate_
limit_ headers - Provider rate-limit response headers -> typed hints (PACE-01)
- reasoning
- Reasoning effort at the wire: exact or refused, never guessed (Phase 51, D-00f).
- redaction
- Credential redaction shared by every provider adapter (not feature-gated — reused by the shared compatible core and by bespoke adapters alike). Credential redaction for diagnostic text.
- registry
- The per-model profile registry (ADR-0061, D-05..D-07): seeded entry, config
registry::ModelOverride, adapter-wide fallback, and the visible unknown-model fallback. Not feature-gated – every adapter resolves its profile through it. The per-model profile registry (ADR-0061 (c), D-05..D-07): whichModelProfileapplies to which model of one provider, and how that was decided. - sampling
- The one wire-time sampling filter every request builder calls (ADR-0061): a set parameter is
sent only when the model’s profile admits it, every omission is logged once and recorded under
sampling::PARAMS_OMITTED_METADATA_KEY. Not feature-gated. The one wire-time sampling filter every request builder calls (ADR-0061). - services
- Application-layer services composing this crate’s ports (provider capabilities,
paladin_ports::output::token_counter_port::TokenCounterPort) rather than implementing a provider adapter themselves. Housesservices::commissary, the v0.10.0-native prompt-budgeting service (fail-loud pre-flight guard + bounded, priority-ordered allocator with explicit truncation markers). Application-layer services inpaladin-llm: composable orchestration built on top of the crate’s port-facing primitives (provider adapters,TokenCounterPort), rather than a provider adapter itself. - usage_
reconcile - The check every usage mapper’s output passes through (G-50-5a): the vendor’s own total and
the containment
paladin_core::platform::container::token_usage::TokenUsagepromises are compared with the mapped usage, and any finding is logged once and recorded underusage_reconcile::USAGE_UNRECONCILED_METADATA_KEY. Not feature-gated. The check every usage mapper’s output passes through (G-50-5a). - window
- The shared context-window precedence resolver (PRIM-04, D-01/D-02): one
pure function,
window::resolve_context_window, that every consumer ofpaladin_ports::output::llm_port::ProviderCapabilitiescalls through instead of writing its own config-table/capability/fallback walk. Not feature-gated — bothservices::commissaryand the facade’sHistoryTrimmerneed it unconditionally. The shared context-window precedence resolver every consumer ofProviderCapabilitiescalls through, instead of writing its own config-table/capability/fallback walk (PRIM-04, D-01/D-02).