SolwynConfig

import os
from anthropic import Anthropic
from openai import OpenAI
from solwyn import Solwyn

client = Solwyn(
    OpenAI(),
    model="gpt-4o",
    api_key=os.environ["SOLWYN_API_KEY"],
    budget_mode="hard_deny",
    fail_open=False,
    fallback=[(Anthropic(), "claude-sonnet-4-5", {"max_tokens": 1024})],
    circuit_breaker_failure_threshold=5,
)

Configuration is passed as keyword arguments to Solwyn() or AsyncSolwyn(). A handful of arguments shape the failover chain and are handled by the client wrapper; the rest map directly onto SolwynConfig fields, many of which also read a SOLWYN_-prefixed environment variable.

SolwynConfig is a Pydantic BaseModel that validates all SDK configuration. You never construct it directly — the wrapper assembles the failover chain (providers, default_params) from the client, model=, fallback=, and default_params= arguments, then constructs and validates the config.

This page is the single source for every configuration option and every environment variable.

Constructor arguments

These keyword-only arguments are handled by the client wrapper itself — they are not raw SolwynConfig fields, and none has an environment variable:

Precedence

Constructor keyword arguments take precedence over environment variables, which take precedence over defaults:

Constructor kwargs  >  SOLWYN_* env vars  >  Defaults

If a field is provided in both the constructor and an environment variable, the constructor value wins.

One runtime exception, new in 0.3.0: on plans without the failover-tuning entitlement, a plan-scoped Cloud directive can advisorily override the seven failover and circuit-breaker tuning fields — failover_total_timeout, failover_idempotency, same_provider_retries, circuit_breaker_recovery_timeout_jitter, circuit_breaker_failure_threshold, circuit_breaker_recovery_timeout, and circuit_breaker_success_threshold — replacing them with SDK defaults at runtime. The override is reversible and applies to no other field; constructor-over-env precedence is unchanged everywhere else. See Plan-scoped tuning entitlement.

Field reference

Required fields

This field must be supplied either as a constructor keyword argument or via the corresponding environment variable. The kwarg defaults to None, and the env-var loader runs before validation, so passing nothing is fine as long as the environment is populated.

Invalid formats raise ConfigurationError immediately at construction time, with the field attribute set to the failing field name.

Core settings

budget_mode values

fail_open values

The SOLWYN_FAIL_OPEN environment variable accepts true, 1, yes (case-insensitive) for True, and any other value for False.

Provider failover chain

These fields are assembled by the client wrapper from your client / model= / fallback= / default_params= arguments. They are constructor-only — none is read from the environment.

ProviderEntry carries provider, model, and default_params only — never an api_key or base_url. Provider credentials live on your client objects.

See Provider Failover for the full failover model, including the per-call solwyn_idempotent override.

Circuit breaker

Lower failure_threshold values react faster to outages but may trigger on transient errors. Lower recovery_timeout values recover faster but may probe before the provider is ready.

Budget

Lower values provide more responsive enforcement at the cost of more API round-trips. Higher values reduce traffic but may allow brief overspend.

Reporter

The metadata reporter sends token-usage events to Solwyn Cloud in batches:

Tuning guidance:

• High-throughput applications: increase reporter_batch_size and reporter_max_queue_size to reduce HTTP overhead.
• Low-latency applications: decrease reporter_flush_interval for faster dashboard updates.
• Memory-constrained environments: decrease reporter_max_queue_size to limit memory usage.

Environment variables

This is the complete, site-wide list of environment variables the SDK reads. Only the fields below are populated from the environment — the failover chain (fallback, model, provider, default_params, selection_policy) and the failover knobs are constructor-only. The prefix is always SOLWYN_, and the suffix is the uppercase field name:

api_key                            -> SOLWYN_API_KEY
api_url                            -> SOLWYN_API_URL
fail_open                          -> SOLWYN_FAIL_OPEN
budget_mode                        -> SOLWYN_BUDGET_MODE
circuit_breaker_failure_threshold  -> SOLWYN_CIRCUIT_BREAKER_FAILURE_THRESHOLD
circuit_breaker_recovery_timeout   -> SOLWYN_CIRCUIT_BREAKER_RECOVERY_TIMEOUT
circuit_breaker_success_threshold  -> SOLWYN_CIRCUIT_BREAKER_SUCCESS_THRESHOLD
breaker_reporting_enabled          -> SOLWYN_BREAKER_REPORTING_ENABLED
budget_check_cache_ttl             -> SOLWYN_BUDGET_CHECK_CACHE_TTL
reporter_batch_size                -> SOLWYN_REPORTER_BATCH_SIZE
reporter_flush_interval            -> SOLWYN_REPORTER_FLUSH_INTERVAL
reporter_max_queue_size            -> SOLWYN_REPORTER_MAX_QUEUE_SIZE
reporter_max_in_flight             -> SOLWYN_REPORTER_MAX_IN_FLIGHT

Constructor values take precedence over environment variables, which take precedence over defaults.

Boolean coercion

The SOLWYN_FAIL_OPEN and SOLWYN_BREAKER_REPORTING_ENABLED environment variables are coerced to booleans: true, 1, yes (case-insensitive) map to True. All other values map to False.

Validation

Credential format validation

The api_key is validated after construction:

• API key: must match the regex ^sk_proj_[a-f0-9]{64}$

Security checks applied:

• Unicode NFC normalization (prevents homograph attacks)
• ASCII-only enforcement (prevents encoding exploits)
• Path traversal rejection (.., /, \ are rejected)

Invalid formats raise ConfigurationError with the field attribute set to the failing field name.

Provider chain validation

The config requires at least one entry in providers. An empty chain raises ConfigurationError on the providers field. In normal use the wrapped client always supplies the primary entry, so this is satisfied automatically.

Extra field rejection

SolwynConfig uses Pydantic's extra="forbid" mode. Any unrecognized keyword argument is rejected:

import os
from openai import OpenAI
from solwyn import Solwyn

# Rejected -- "typo_field" is not recognized.
# The removed fallback_model / primary_provider options are also rejected here.
client = Solwyn(
    OpenAI(),
    api_key=os.environ["SOLWYN_API_KEY"],
    typo_field="value",
)

Use fallback=[...] for failover (see Provider Failover); the primary provider is always auto-detected from the wrapped client.

Enum values

BudgetMode

ProviderName

The first four values are native API dialects (Bedrock's Converse API is its own dialect). The rest are OpenAI-compatible providers: they speak the Chat Completions dialect but are distinct providers for attribution, pricing, budget enforcement, and circuit breaking.

CircuitState

FailoverReason

Example: full configuration

import os
from anthropic import Anthropic
from openai import OpenAI
from solwyn import Solwyn, LatencyPolicy

client = Solwyn(
    OpenAI(),
    # Primary entry
    model="gpt-4o",
    # Required
    api_key=os.environ["SOLWYN_API_KEY"],
    # Core
    api_url="https://api.solwyn.ai",
    budget_mode="hard_deny",
    fail_open=False,
    # Failover chain
    fallback=[(Anthropic(), "claude-sonnet-4-5", {"max_tokens": 1024})],
    default_params={"temperature": 0.7},
    selection_policy=LatencyPolicy(),
    failover_total_timeout=20.0,
    failover_idempotency="safe",
    same_provider_retries=1,
    # Circuit breaker
    circuit_breaker_failure_threshold=5,
    circuit_breaker_recovery_timeout=30,
    circuit_breaker_success_threshold=3,
    # Budget
    budget_check_cache_ttl=10,
    # Reporter
    reporter_batch_size=100,
    reporter_flush_interval=2.0,
    reporter_max_queue_size=20000,
    reporter_max_in_flight=5,
)