Adapters

Adapters are the bridge between your LLM provider's native SDK and BeliefState's universal tracking pipeline. Each adapter implements the ProviderAdapter protocol, handling two critical jobs:

1. Payload normalization: Converting provider-specific request/response formats into BeliefState's universal LLMCall and LLMResponse models.
2. Internal LLM operations: Executing belief extraction prompts, generating vector embeddings for semantic search, and running NLI judge checks.

All adapters include built-in production features:

Choosing an Adapter

OpenAI

The OpenAI adapter supports all GPT chat completion models and OpenAI's embedding models. It uses the official openai Python SDK with async client support. The API key is read from the OPENAI_API_KEY environment variable, or can be passed via a pre-configured client instance.

Constructor Parameters

pythonfrom beliefstate.adapters import OpenAIAdapter

adapter = OpenAIAdapter(
    model="gpt-4o",                        # Chat completion model
    embed_model="text-embedding-3-small",   # Embedding model
    timeout=30.0,                           # Request timeout (seconds)
)

# Health check — verify API key and connectivity
is_healthy = await adapter.health_check()

Anthropic (Claude)

The Anthropic adapter supports all Claude models. It uses the official anthropic Python SDK. The API key is read from the ANTHROPIC_API_KEY environment variable.

Constructor Parameters

pythonfrom beliefstate.adapters import AnthropicAdapter

adapter = AnthropicAdapter(
    model="claude-3-5-sonnet-latest",
    timeout=30.0
)

Google Gemini

The Gemini adapter supports Google's Generative AI models through the google-generativeai SDK. It provides both chat completion and embedding capabilities. The API key is read from GOOGLE_API_KEY or GEMINI_API_KEY environment variable.

Constructor Parameters

pythonfrom beliefstate.adapters import GeminiAdapter

adapter = GeminiAdapter(
    model="gemini-2.0-flash",
    embed_model="text-embedding-004",
    timeout=30.0
)

Set GOOGLE_API_KEY or GEMINI_API_KEY environment variable.

Ollama (Local)

The Ollama adapter connects to a locally running Ollama server for completely free, offline LLM inference. It supports any model available in your local Ollama installation. Ollama is the recommended choice as an internal_adapter in the Dual-Adapter pattern — zero API costs for background tracking.

Constructor Parameters

pythonfrom beliefstate.adapters import OllamaAdapter

adapter = OllamaAdapter(
    model="llama3.2",
    embed_model="nomic-embed-text",
    host="http://localhost",
    port=11434
)

LiteLLM (Multi-Provider)

The LiteLLM adapter uses the LiteLLM library to route requests to 100+ LLM providers through a unified API. It supports Azure OpenAI, AWS Bedrock, Cohere, Vertex AI, and many more. Provider-specific API keys are configured via environment variables as documented by LiteLLM.

Constructor Parameters

pythonfrom beliefstate.adapters import LiteLLMAdapter

# Route to any of 100+ providers via LiteLLM
adapter = LiteLLMAdapter(
    model="azure/gpt-4",                    # Azure OpenAI
    embed_model="cohere/embed-english-v3.0"  # Cohere embeddings
)

# Or use AWS Bedrock
adapter = LiteLLMAdapter(model="bedrock/anthropic.claude-3-sonnet")

RetryConfig

All adapters accept an optional RetryConfig that controls how transient API errors (rate limits, timeouts, server errors) are retried. The default configuration uses exponential backoff with jitter to avoid thundering herd problems when a provider recovers from an outage.

Constructor Parameters

pythonfrom beliefstate.adapters.common import RetryConfig

# Conservative retry for rate-limited APIs
config = RetryConfig(
    max_retries=5,
    initial_delay=2.0,
    max_delay=60.0,
    exponential_base=2.0,
    jitter=True,
)

# Pass to any adapter
adapter = OpenAIAdapter(model="gpt-4o", retry_config=config)

Retry Delay Schedule (with defaults)

With initial_delay=1.0, exponential_base=2.0, max_delay=30.0, and jitter=True:

Transient vs. Permanent Errors

The retry mechanism only retries transient errors — those that might succeed on a subsequent attempt. These include:

• Rate limit errors (HTTP 429) — Provider is throttling requests
• Server errors (HTTP 500, 502, 503) — Provider is temporarily unavailable
• Timeout errors — Request took too long
• Connection errors — Network issues

Permanent errors (invalid API key, malformed request, model not found) are raised immediately without retrying.

Dual-Adapter Architecture

The Dual-Adapter pattern lets you use a premium model for your application's user-facing responses and a cheaper/local model for all background belief tracking work. This can reduce tracking costs by 90%+ while maintaining identical application quality.

When to Use Dual-Adapter

• Cost optimization: Your app uses GPT-4o ($$$) but tracking can run on Llama 3 via Ollama (free).
• Anthropic users: Claude doesn't offer an embedding API — you must use a second adapter for embeddings.
• Privacy: Keep user data local by running extraction on Ollama while the app uses a cloud provider.
• Latency: Offload tracking to a fast local model so it doesn't compete for API rate limits.

pythonfrom beliefstate.adapters import AnthropicAdapter, OllamaAdapter

# Your app uses Claude 3.5 Sonnet (premium)
app_adapter = AnthropicAdapter(model="claude-3-5-sonnet-latest")

# Background tracking uses local Llama 3 (free!)
bg_adapter = OllamaAdapter(model="llama3", embed_model="nomic-embed-text")

tracker = BeliefTracker(
    config=config,
    adapter=app_adapter,              # Intercepts the Claude API payload
    internal_adapter=bg_adapter       # Runs extraction, embeddings, and judge
)

How It Works

  ┌─────────────────────┐                 ┌─────────────────────┐
  │   App Adapter       │                 │  Internal Adapter   │
  │ (Claude 3.5 Sonnet) │                 │  (Ollama / Llama3)  │
  │                     │                 │                     │
  │  • to_llm_call()    │                 │  • generate()       │
  │  • to_llm_response()│    ────────▶    │  • get_embeddings() │
  │  (payload parsing)  │  belief tasks   │  • health_check()   │
  └─────────────────────┘                 └─────────────────────┘

Payload Normalization

Different model providers use radically different SDK payload signatures. For example:

• OpenAI: Accesses response text via response.choices[0].message.content.
• Anthropic: Accesses response text via response.content[0].text.
• Google Gemini: Accesses response text via response.text.

Each adapter implements the ProviderAdapter protocol to normalize inputs and outputs:

• to_llm_call(*args, **kwargs): Intercepts raw arguments passed to the provider SDK and extracts the conversation history, converting them into a standardized LLMCall structure containing a unified list of message dictionaries.
• to_llm_response(raw_response): Normalizes the provider's returned response object into an LLMResponse structure, exposing the message content, model name, and token usage metadata.

This decoupling is what enables the Dual-Adapter pattern: the premium adapter parses the main application LLM calls, while the internal adapter handles all background vector embeddings, fact extractions, and logical checks using completely different API calls.