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 and widened in 0.4.0: on plans without the failover-tuning entitlement, a plan-scoped Cloud directive can advisorily override the eight failover and circuit-breaker tuning fields — failover_total_timeout, failover_hop_read_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.

Breaking in 0.6.0: both timeouts reject booleans, NaN, +inf, and -inf at construction. float("inf") was previously accepted and produced an unbounded failover window or hop read. Through Solwyn(...) the rejection is a ConfigurationError whose field names the timeout; constructing SolwynConfig directly raises pydantic's ValidationError.

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.

Control plane

New in 0.4.0. These govern a circuit breaker around Solwyn Cloud itself, so a Solwyn outage is discovered once per client rather than re-paid on every call. It is a separate health domain from the per-provider breakers above, is never included in breaker state reports, and never denies a call on its own — it only decides how fast the SDK stops waiting on an unreachable control plane.

A read-only-key refusal means Solwyn responded, so it records a success and never opens this breaker. See Read-only key diagnostics.

Budget

budget_check_cache_ttl applies to the per-call check path only — it never authorizes a lease-funded call, and run-scoped and tagged checks bypass it. SDK v0.6.0+: the cache is a bounded 16-entry LRU keyed by provider, model, the fallback chain, and modality; a hit replays that entry's own price hints and never a reservation id. Lower values give more responsive enforcement at the cost of more API round-trips; higher values reduce traffic but may allow brief overspend.

Coverage

SDK v0.6.0+. How the wrapper treats provider capabilities Solwyn does not meter. See Coverage controls.

Velocity

SDK v0.6.0+. Local runaway-run detection inside a solwyn.run(...) scope. It runs entirely in-process on token counts and timing — never on content — and either warns or stops the run. See Local velocity detection.

repeat_size and monotonic_growth can stop a run under deny; rate_acceleration is advisory only. A local stop is never lifted by a server allow — only solwyn.clear_run_termination(run_id) clears it.

Reporter

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

Delivery retry and shutdown, new in 0.4.0 — see Spend delivery:

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.
• Short-lived processes (CLI jobs, serverless handlers): raise reporter_shutdown_deadline if close() is dropping spend on exit, or lower it if an unreachable Solwyn is holding up teardown.

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, control_plane_transport) and the failover knobs, including failover_hop_read_timeout, 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
tags                               -> SOLWYN_TAGS
on_unmetered                       -> SOLWYN_ON_UNMETERED
acknowledge_untracked              -> SOLWYN_ACKNOWLEDGE_UNTRACKED
report_untracked_surfaces          -> SOLWYN_REPORT_UNTRACKED_SURFACES
velocity_mode                      -> SOLWYN_VELOCITY_MODE
velocity_repeat_count              -> SOLWYN_VELOCITY_REPEAT_COUNT
velocity_repeat_window_s           -> SOLWYN_VELOCITY_REPEAT_WINDOW_S
velocity_growth_streak             -> SOLWYN_VELOCITY_GROWTH_STREAK
velocity_growth_factor             -> SOLWYN_VELOCITY_GROWTH_FACTOR
velocity_accel_floor_per_min       -> SOLWYN_VELOCITY_ACCEL_FLOOR_PER_MIN
velocity_accel_factor              -> SOLWYN_VELOCITY_ACCEL_FACTOR
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
breaker_report_heartbeat           -> SOLWYN_BREAKER_REPORT_HEARTBEAT
budget_check_cache_ttl             -> SOLWYN_BUDGET_CHECK_CACHE_TTL
budget_check_timeout               -> SOLWYN_BUDGET_CHECK_TIMEOUT
lease_enabled                      -> SOLWYN_LEASE_ENABLED
lease_output_bound_default         -> SOLWYN_LEASE_OUTPUT_BOUND_DEFAULT
control_plane_failure_threshold    -> SOLWYN_CONTROL_PLANE_FAILURE_THRESHOLD
control_plane_recovery_timeout     -> SOLWYN_CONTROL_PLANE_RECOVERY_TIMEOUT
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
reporter_max_send_attempts         -> SOLWYN_REPORTER_MAX_SEND_ATTEMPTS
reporter_retry_backoff_base        -> SOLWYN_REPORTER_RETRY_BACKOFF_BASE
reporter_retry_backoff_cap         -> SOLWYN_REPORTER_RETRY_BACKOFF_CAP
reporter_shutdown_deadline         -> SOLWYN_REPORTER_SHUTDOWN_DEADLINE

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

Boolean coercion

The SOLWYN_FAIL_OPEN, SOLWYN_BREAKER_REPORTING_ENABLED, SOLWYN_LEASE_ENABLED, and SOLWYN_REPORT_UNTRACKED_SURFACES environment variables are coerced to booleans: true, 1, yes (case-insensitive) map to True. All other values map to False — including a typo, so SOLWYN_REPORT_UNTRACKED_SURFACES=TRUE_ silently disables a default-on feature.

Validation

Tags

SOLWYN_TAGS entries must be key=value; an entry without = (which is what a comma inside a value produces) raises ConfigurationError(field="tags"). A set-but-empty SOLWYN_TAGS= raises for the same reason — unset the variable rather than clearing it. The same bounds apply to the constructor mapping: at most 10 keys, keys 1–64 characters, values 0–256, no NUL, all strings.

Timeouts

failover_total_timeout and failover_hop_read_timeout must be finite numbers; the hop read timeout must also be greater than zero. Booleans are rejected explicitly ("timeout bounds must be numbers, not booleans").

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 auto-detected from the wrapped client unless you pin it with provider=.

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

DenySource

SDK v0.6.0+. The deny_source on a denial receipt:

Example: full configuration

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

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,
    tags={"environment": "production", "service_name": "research"},
    # Coverage
    on_unmetered="raise",
    acknowledge_untracked={"models.list"},
    report_untracked_surfaces=True,
    # Velocity
    velocity_mode="deny",
    velocity_repeat_count=8,
    # Failover chain
    fallback=[(Anthropic(), "claude-sonnet-4-5", {"max_tokens": 1024})],
    default_params={"temperature": 0.7},
    selection_policy=CostPolicy(),
    failover_total_timeout=20.0,
    failover_hop_read_timeout=120.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,
    breaker_report_heartbeat=60.0,
    # Control plane
    control_plane_failure_threshold=3,
    control_plane_recovery_timeout=30.0,
    # Budget
    budget_check_cache_ttl=10,
    budget_check_timeout=1.0,
    lease_enabled=True,
    lease_output_bound_default=4096,
    # Reporter
    reporter_batch_size=100,
    reporter_flush_interval=2.0,
    reporter_max_queue_size=20000,
    reporter_max_in_flight=5,
    reporter_max_send_attempts=5,
    reporter_retry_backoff_base=1.0,
    reporter_retry_backoff_cap=60.0,
    reporter_shutdown_deadline=5.0,
)