Pages
Adapters Sections
Overview OpenAI Anthropic Google Gemini Ollama LiteLLM Dual-Adapter

Reference

Adapters

Adapters normalise provider-specific SDK formats into BeliefState's universal LLMCall and LLMResponse models.

Adapters

Adapters convert the unique data formats utilized by different LLM vendor SDKs into normalized inputs. This abstraction isolates the tracking codebase from varying payload signatures.

Additionally, adapters handle internal operations required to run the tracking pipeline. This includes executing belief extraction prompts, computing vector embeddings for similarity checking, and running contradiction evaluations.

Automatic Retry Timeout Handling Health Checks Structured Logging API Key Validation

Choosing an Adapter

Adapter Best For Embeddings Cost
OpenAI Widest model selection and extraction quality. Supported Pay per token usage.
Anthropic Complex logical reasoning and long conversations. None — use Dual-Adapter Pay per token usage.
Gemini Large context reasoning and Flash models. Supported Pay per token usage.
Ollama Zero cost, local execution, and complete privacy. Supported Free (local computation).
LiteLLM Multi-provider proxy routing and enterprise hubs. Supported Varies by backend provider.

OpenAI

The OpenAI adapter integrates with all GPT chat completion models and embedding endpoints. The adapter reads authorization credentials from the OPENAI_API_KEY environment variable.

openai_setup.py
from beliefstate.adapters import OpenAIAdapter adapter = OpenAIAdapter( model="gpt-4o", embed_model="text-embedding-3-small", timeout=30.0 ) # Verify credentials and network state is_healthy = await adapter.health_check()
Parameter Type Default Description
client Optional[AsyncOpenAI] None Pre-configured AsyncOpenAI client instance. Overrides automatic environment lookup.
model str "gpt-4o-mini" Chat model used for extraction and logical check processing.
embed_model str "text-embedding-3-small" Vector model used to calculate belief embeddings.
embed_kwargs Optional[dict] {} Additional keyword arguments forwarded to the embedding API.
timeout float 30.0 Max request duration in seconds before raising a timeout exception.
retry_config Optional[RetryConfig] RetryConfig() Retry configuration rules for handling transient exceptions.
💡 Tip

Set OPENAI_API_KEY as an environment variable, or pass a pre-configured client directly: OpenAIAdapter(client=AsyncOpenAI(api_key="sk-...")).

Anthropic (Claude)

The Anthropic adapter manages Claude models using the official Python client. Set the ANTHROPIC_API_KEY environment variable to authorize connection requests.

anthropic_setup.py
from beliefstate.adapters import AnthropicAdapter adapter = AnthropicAdapter( model="claude-3-5-sonnet-latest", timeout=30.0 )
Parameter Type Default Description
client Optional[AsyncAnthropic] None Pre-configured AsyncAnthropic client. If None, initialized from environment variables.
model str "claude-3-5-sonnet-latest" Claude chat model identifier used for core prompt evaluation.
timeout float 30.0 Timeout limit in seconds per API request.
retry_config Optional[RetryConfig] RetryConfig() Retry settings for transient network operations.
⚠ Important

No Embedding API: Anthropic does not provide embeddings. Use the Dual-Adapter pattern with OpenAI or Ollama as internal_adapter for embedding generation. Without a secondary embedding source, contradiction checks will raise a NotImplementedError.

Google Gemini

The Gemini adapter integrates Google's Generative AI models. Credentials must reside in the GOOGLE_API_KEY or GEMINI_API_KEY environment variables.

gemini_setup.py
from beliefstate.adapters import GeminiAdapter adapter = GeminiAdapter( model="gemini-2.0-flash", embed_model="text-embedding-004", timeout=30.0 )
Parameter Type Default Description
client Optional[Any] None Pre-configured Google GenerativeAI client instance.
model str "gemini-2.0-flash" Gemini model identifier used for conversational processing.
embed_model str "text-embedding-004" Google model used to calculate vector representations.
timeout float 30.0 Timeout duration limit in seconds.
retry_config Optional[RetryConfig] RetryConfig() Retry settings for transient network operations.
Note

Set the GOOGLE_API_KEY or GEMINI_API_KEY environment variable in your deployment configuration before running the tracking layer.

Ollama (Local)

The Ollama adapter runs local, offline models. It requires an active Ollama instance running on your machine.

ollama_setup.py
from beliefstate.adapters import OllamaAdapter adapter = OllamaAdapter( model="llama3.2", embed_model="nomic-embed-text", host="http://localhost", port=11434 )
Parameter Type Default Description
client Optional[AsyncClient] None Pre-configured Ollama client instance. If None, initialized from host and port.
model str "llama3.2" Local model name used for processing. Ensure this model is pulled locally.
embed_model str "nomic-embed-text" Local embedding model name used for vector generation.
host str "http://localhost" Ollama server hostname.
port int 11434 Ollama server listener port.
timeout float 120.0 Max request timeout. Set higher for local execution on non-GPU setups.
retry_config Optional[RetryConfig] RetryConfig() Retry settings for transient connections.
💡 Tip

Ollama is the recommended internal_adapter — completely free, runs locally. Pull both models before running: ollama pull llama3.2 && ollama pull nomic-embed-text.

LiteLLM (Multi-Provider)

The LiteLLM adapter utilizes the LiteLLM proxy client, letting you integrate with over 100 hosting APIs using unified parameters.

litellm_azure.py
from beliefstate.adapters import LiteLLMAdapter # Configure Azure OpenAI connection adapter = LiteLLMAdapter( model="azure/gpt-4", embed_model="cohere/embed-english-v3.0" )
litellm_bedrock.py
from beliefstate.adapters import LiteLLMAdapter # Configure AWS Bedrock connection adapter = LiteLLMAdapter( model="bedrock/anthropic.claude-3-sonnet" )
Parameter Type Default Description
model str required LiteLLM formatted model name (e.g., "azure/gpt-4").
embed_model str None LiteLLM formatted embedding model. Raises an error if embeddings are executed without setting this.
timeout float 30.0 Max request duration limit.
retry_config Optional[RetryConfig] RetryConfig() Retry settings for transient proxy connections.
Note

Refer to the official LiteLLM documentation to retrieve provider-specific prefix requirements and model names.

RetryConfig

All adapters accept RetryConfig for transient error handling.

retry_setup.py
from beliefstate.adapters.common import RetryConfig config = RetryConfig( max_retries=3, initial_delay=1.0, max_delay=30.0, exponential_base=2.0, jitter=True )
Parameter Type Default Description
max_retries int 3 Maximum number of retries before propagating errors.
initial_delay float 1.0 Base waiting time in seconds before executing the first retry.
max_delay float 30.0 Maximum retry delay limit in seconds. Caps backoff duration.
exponential_base float 2.0 Exponential delay multiplier.
jitter bool True Enables random noise shifts in delay times to prevent thundering herd conditions.

Retry Delay Schedule

Attempt Computed Delay With Jitter (range)
1 1.0s 0.5s – 1.0s
2 2.0s 1.0s – 2.0s
3 4.0s 2.0s – 4.0s

Retried Errors

  • HTTP 429 — Rate limit throttling
  • HTTP 5xx — Transient server outages
  • API Timeout — Connection requests timed out
  • Connection Errors — TCP network errors

Never Retried

  • Authentication — Invalid API Key credentials
  • Validation — Invalid models or arguments
  • Malformed JSON — Bad API request structure

Dual-Adapter Architecture

Use a premium model for users, a cheap model for tracking.

Identify scenarios that benefit from a dual-adapter configuration:

  • Cost optimisation — Deliver user responses via premium endpoints, and offload calculations locally.
  • Anthropic users — Route embedding generations to local or cheap vector APIs since Claude has no embed endpoints.
  • Privacy — Process belief extractions locally using internal models to isolate sensitive details.
  • Latency — Execute tracking pipelines locally to preserve rate limits on user-facing endpoints.
dual_adapter.py
from beliefstate import BeliefTracker, TrackerConfig from beliefstate.adapters import AnthropicAdapter, OllamaAdapter app_adapter = AnthropicAdapter(model="claude-3-5-sonnet-latest") bg_adapter = OllamaAdapter(model="llama3", embed_model="nomic-embed-text") tracker = BeliefTracker( config=TrackerConfig(), adapter=app_adapter, internal_adapter=bg_adapter )
architecture.txt
┌─────────────────────┐ ┌─────────────────────┐ │ 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 Normalisation

Different provider SDKs return responses using unique payload layouts. The adapter normalizes these formats into standard Python properties:

openai_payload.py
# OpenAI payload content extraction content = response.choices[0].message.content
anthropic_payload.py
# Anthropic payload content extraction content = response.content[0].text
gemini_payload.py
# Gemini payload content extraction content = response.text