SOLWYN

Changelog

Solwyn Python SDK release history

All notable changes to the Solwyn Python SDK are documented here. This project follows Semantic Versioning.

0.11.0 (2026-11-05)

API key scoping. Keys belong to your account and can reach one or more projects, so every client now names the project it spends against. This release needs a Solwyn API that supports scoped keys. Old project keys stop working at the same time.

Breaking

  • New key format and a required project. Keys are solwyn_sk_ followed by 64 lowercase hex characters. Pass the project with project= or set SOLWYN_PROJECT: a project name or a proj_ id. A client without one raises ConfigurationError(field="project"). Old sk_proj_ keys are rejected at construction, with a message that says to create a new key in the dashboard or with solwyn keys create.
  • project_id= and SOLWYN_PROJECT_ID are gone. project_id= raises ConfigurationError (it used to raise TypeError). SOLWYN_PROJECT_ID is not read; if it is set and no project is configured, the error says to rename it to SOLWYN_PROJECT.
  • A read-only key is refused, not tolerated. It used to log one error and let calls continue unmetered. It now fails validate() and blocks every call, whatever fail_open says.
  • solwyn.testing: FakeControlPlane.wrap() reserves project, the plane's key is a solwyn_sk_ key, and every request to it must name the project. The solwyn.testing.contract functions take the project as a new third argument.

Added

  • Solwyn-Project on every request. The SDK sends the configured project until it validates, then the project's proj_ id, so renaming the project in the dashboard does not break a running client. The old name fails at the next start.
  • Lazy validation and validate(). Constructing a client makes no network call. Before the first call that needs Solwyn, the SDK checks the key once with GET /api/v1/auth/key. client.validate() (await client.validate() on AsyncSolwyn) runs the same check on demand, returns the key's details, raises on any refusal, and returns None when Solwyn can't be reached. See validate().
  • ApiKeyRefusedError, a ConfigurationError with code and field, raised when Solwyn refuses the key or the project. See ApiKeyRefusedError.

Changed

  • A refusal is never an outage. Every 401 from Solwyn is a key refusal. A refusal is checked before anything else on every call: no cached allow, held lease, open control-plane breaker or fail_open setting lets a call past it. The SDK re-checks the key (at once after a 401, then every 60 seconds while Solwyn keeps refusing) and recovers on the first success. While a refusal is stored, the SDK sends Solwyn nothing but that re-check; queued usage is dropped and counted as api_key_refused.
  • Alert-only projects keep running when a key expires. After the client has validated once, an expired or revoked key on a project that promises to block nothing (alert-only, with no unpaused hard budget rule or run cap) lets calls run unmetered, logging solwyn.api_key_refused at error on every call. Every other refusal blocks, and at startup every refusal blocks.
  • What a refusal stops. A refusal stops every provider call admitted after it is recorded, including calls through objects the client handed out earlier (derived clients, sessions, stream helpers, pages). A call that had already passed Solwyn's checks may still complete.

0.10.2 (2026-11-03)

hard_deny fixes: a stream closed early or dropped, and a call that fails in an unrecognized way after it was sent, no longer give back budget they may have spent. Keeping that funding is now hard_deny only. Under hard_deny, a call whose usage can't be measured and may have been billed is recorded at its reserved amount, marked estimated, so the dashboard can show more than the provider billed (for example, a stream you stopped early). This needs Solwyn API support that is live from 2026-11-02.

Added

  • Anthropic SDK 2.4 support. The administration APIs Anthropic 2.4 promotes from beta.organization to organization (analytics, rbac_groups, rbac_roles, spend_limits) are classified like their beta predecessors: unmetered, following on_unmetered.

Fixed

  • A stream closed before its end keeps its funding (hard_deny). It used to settle at the usage seen so far, often zero, so a lease claim or per-call hold went back while the provider could still bill the whole generation. It now confirms its floor (the reservation's estimated input and output bound, or the observed usage where larger), marked estimated. A stream dropped without close() settles the same way when it is collected, and closing the client settles every stream it returned that is still open.
  • An unrecognized failure after dispatch keeps its funding. After a request was sent, a failure keeps its bound unless it has a 4xx status (429 included), a 529, or a transport error that proves nothing was sent.
  • Possibly billed spend is recorded durably (hard_deny). Those paths now send a floor confirm that Solwyn keeps as a durable receipt, so the cap can't be passed after the lease or hold ends.
  • A response whose body fails to decode no longer fails over under the default failover_idempotency="safe": it is treated as possibly billed, like a read timeout.

Changed

  • Keeping possibly billed funding is hard_deny only. On alert_only, those calls settle once at their observed usage and release the claim, as before 0.10.1.

0.10.1 (2026-11-02)

hard_deny fixes: it now also covers failover hops and decisions.create. In both cases a call could spend past a hard_deny budget.

Fixed

  • A failover hop is checked at its own price. On a hard_deny project, before a call is sent to a hop whose provider or model differs from what was admitted, Solwyn frees the earlier reservation and checks the hop at its own price and output bound. A hop that does not fit is refused with BudgetExceededError and never called. Any attempt after a possibly billed one is checked again, even on the same provider and model.
  • A lease covers (provider, model) pairs, not model names, so a declared model served by another provider takes a per-call check.
  • hard_deny allows are no longer cached. Every hard_deny call gets its own check; alert_only allows are still cached.
  • decisions.create is refused on hard_deny projects with OutputBoundUnenforceableError and the reason no_output_cap, because it takes no output cap. It still runs on alert_only projects.
  • A call refused before any provider request no longer holds budget: its per-call reservation is settled at zero.

0.10.0 (2026-10-31)

A hard_deny budget now bounds a call's output, not only its input. Every per-call text budget check sends the call's output bound. On a hard_deny admission, a request with no output cap is sent to the provider with one, so chat, beta Messages and Responses calls go out with a cap no larger than the bound Solwyn reserved. Some surfaces are not capped; OpenAI decisions.create, for one, sends the default bound on its check but is never capped (see the limitations below). The bound limits tokens, not dollars: admission prices the primary model with an estimated input, so a call that fails over to a pricier model, or whose input was underestimated, can still settle above its reservation. Before this release, one uncapped or large-cap call on an expensive reasoning model could pass a $1 cap and spend several dollars with no output limit at all. Nothing changes for calls admitted in alert_only mode (the check's effective mode, which is hard_deny when a hard-deny scoped rule or per-run cap applies, even on an alert_only project). The wire-contract change is API-first: Solwyn Cloud accepts estimated_output_bound on POST /api/v1/budgets/check before this release. An older API rejects the field with a 422, which the SDK treats as an unreachable control plane. See What hard_deny bounds.

Changed

  • On hard_deny admissions, uncapped calls are capped at lease_output_bound_default (4096 by default, configurable), because an unbounded call cannot honestly be held to a hard cap. Set your own cap to choose a different limit. The cap goes in the dialect's own field: max_completion_tokens or max_tokens for OpenAI-dialect providers, max_completion_tokens for every Azure OpenAI deployment, max_output_tokens for Responses, max_tokens for Anthropic, config.max_output_tokens for Google (generation_config on the legacy SDK), and inferenceConfig.maxTokens for Bedrock. It is added only when Solwyn admitted the call under hard_deny: a check allow in hard_deny mode (live or from the allow cache), or a lease-funded call whose lease posture was hard_deny when its tokens were reserved. Alert-only, fail-open, outage and uncounted expired-lease admissions send the request exactly as you built it. An explicit positive cap is always sent as is; a zero, negative or non-integer cap in a named argument or default counts as no cap. Chat, beta Messages and Responses calls are capped; OpenAI decisions.create sends the default bound on its check but is never capped or checked against it.
  • Azure OpenAI keeps a caller's max_completion_tokens. It was rewritten to the weaker max_tokens when the deployment name did not look like a reasoning model. When layers disagree, only the cap key of the highest layer that sets one is sent. See Azure OpenAI.

Added

  • estimated_output_bound on the per-call budget check. For each configured provider hop: its output cap (else lease_output_bound_default), plus any reasoning the provider generates outside the cap, times its candidate count (n, Google candidate_count). The largest across the chain is sent. Caps are read the way the request is sent: OpenAI and Anthropic extra_body over named arguments, Google defaults merged field by field, and Google generation_config and camelCase aliases. Qwen's thinking_budget is added unless enable_thinking is False. The API reserves input plus that many output tokens at the model's output rate, so in hard_deny a call whose bound would overrun the remaining budget is refused before the provider is called. Media checks omit the field. A direct check_budget caller that passes no bound on a text check sends the default. The same bound funds lease reservations.
  • OutputBoundUnenforceableError (code="output_bound_unenforceable", with provider, reason and hint). On a hard_deny admission, Solwyn checks the request the provider would receive and refuses it locally when its output cannot be bounded or exceeds the priced bound, normally before any provider I/O. Reasons: malformed_cap_container, malformed_candidate_count, reasoning_without_budget (Qwen thinking without a budget, xAI reasoning models), unsupported_override, multi_generation_loop, azure_api_version (an uncapped call on an api-version before 2024-09-01), and bound_exceeded. The failover chain stops. A lease-funded call hands its local lease claim back; a per-call reservation in Solwyn Cloud stays held until it expires. The Anthropic one-generation middleware can refuse after an earlier send in the same call succeeded; that call has already produced a paid generation, reports possibly_succeeded, and keeps its reservation at the bound. See Exceptions.
  • Body extensions are allowlisted under hard_deny. A body extension may carry only keys the bound accounts for: OpenAI-style extra_body max_tokens, max_completion_tokens and n (plus Qwen enable_thinking and thinking_budget), Anthropic extra_body max_tokens, and Bedrock additionalModelRequestFields thinking. Responses extra_body and Google http_options.extra_body may carry nothing. Any other key, including model, refuses the call with unsupported_override. Responses keeps its existing check in every mode: an extra_body that overrides model, input, instructions, max_output_tokens or stream raises ConfigurationError before the budget check, so only the remaining keys reach the allowlist. A malformed cap inside extra_body (for example max_tokens: 0) is not replaced by the default and refuses with bound_exceeded.
  • A hard_deny call makes exactly one model generation. Google automatic continuation and automatic function calling (both on by default in google-genai) are turned off when unset and refused with multi_generation_loop when turned on. Anthropic fallbacks and clients carrying BetaRefusalFallbackMiddleware are refused the same way. Anthropic clients get an innermost Solwyn middleware that checks every send and lets only one generation go out per call; a request after a successful response is refused before it is sent, with a possibly_succeeded receipt and the reservation kept at its bound. Retries after a failed attempt still pass.
  • Current Qwen and xAI endpoints are detected. Every Model Studio base URL (*.dashscope.aliyuncs.com, including Hong Kong and the Coding Plan, and *.maas.aliyuncs.com workspace, trial and token plan hosts) is Qwen, and regional hosts (*.api.x.ai) are xAI, so their reasoning rules apply.
  • Qwen and Grok models are recognized on any host. Under hard_deny, an auto-detected provider without its own reasoning rule classifies the model id (the last / segment): qwen* and qwq* follow the Qwen rule, grok* the xAI rule. Set provider= explicitly to opt out.
  • BudgetCheckResult.hard_deny_admitted (default False) records whether Solwyn's own authority admitted the call under hard_deny.
  • OpenAI SDK 3.42 support. Coverage reports recognize admin.organization.external_keys, beta.agents.automations with its invocations, and audio.voices.delete. Each is a guarded, unmetered surface that follows on_unmetered and needs an exact acknowledgment token in strict mode. An automation invocation starts a server-side agent run that Solwyn cannot budget or settle, like beta.agents.sessions, so a hard_deny budget does not cover it; set on_unmetered="raise" to refuse it. Coverage fingerprints are refreshed for this admission.

Fixed

  • The allow cache no longer admits a larger call on a smaller call's allow. The output bound is part of the cached cohort, so an allow priced for a 100-token cap cannot admit a 10,000-token call inside the cache window.

Known limitations

  • The SDK release notes list a scoped hard_deny rule (for example a tag or run cap) on an alert_only project as invisible in the check's mode, so its uncapped calls would not be capped. Solwyn Cloud now reports the effective mode on the check, hard_deny whenever an enforcing cap applies, so the SDK caps those calls too. See Effective mode.
  • Reasoning is treated as inside the cap for every provider except Qwen and xAI. That is unverified for DeepSeek, Groq, Mistral, Z.ai, Perplexity and Fireworks.
  • A Qwen thinking-only model that ignores enable_thinking=False can still reason past the bound.
  • The one-generation middleware covers Anthropic clients only: google-genai and the OpenAI SDK have no per-call transport hook. Google relies on the continuation and function-calling rules, and the OpenAI-style metered paths have no internal generation loop.
  • Anthropic compaction through the typed beta context_management parameter is not proven to stay within max_tokens and is not checked.
  • The bound limits output tokens, not dollars. The reservation prices the primary model with a length-based input estimate, so a call that fails over to a more expensive model, or whose input was underestimated, can settle above what it reserved.
  • OpenAI decisions.create uses the media call path: its check sends the default bound, but its output is never capped or checked.

0.9.0 — 2026-10-25

The SDK now meters Anthropic beta.messages.create and OpenAI decisions.create, and counts Anthropic server-side compaction in settled token usage. A new optional OpenTelemetry layer correlates metadata events with the caller's active trace and can emit content-free solwyn.call and solwyn.run spans. Runs stepped by fresh-context generators such as Starlette StreamingResponse keep their attribution, wrapped Anthropic Bedrock clients keep the caller's transport and AWS profile, and strict mode no longer refuses client.timeout reads. The SDK is tested against the new anthropic 2.x and together 3.x majors, and the surface ledger admits openai 3.33 through 3.37, anthropic 1.15 through 2.3, together 2.41 and 3.0, and google-genai 2.31. No existing export or signature changed; three SolwynConfig fields, the solwyn[otel] extra, and one contract-pack function were added. The wire-contract change is API-first: Solwyn Cloud accepts the compaction_* token_details keys and the optional trace_id / span_id / trace_sampled metadata fields before this SDK release.

Added

  • Optional OpenTelemetry trace correlation — metadata events carry the caller's active trace ID, span ID, and sampled flag, including streaming, failover, and denied calls. These are random identifiers, never content, and are omitted when no valid span is active. On by default whenever opentelemetry-api is importable (solwyn[otel] installs it as a convenience); disable with trace_correlation=False or SOLWYN_TRACE_CORRELATION=false. See Trace correlation.
  • Opt-in solwyn.call and solwyn.run spans — otel_spans=True or SOLWYN_OTEL_SPANS=true emits a solwyn.call span around budget preflight, provider dispatch, failover, and stream lifetime, and solwyn.run spans for run scopes and lifecycle handles. Attributes come from a closed solwyn.* allowlist of call, routing, budget, and run-ID metadata, never cost, token usage, content, tags, or exception messages. Budget checks and native provider spans nest beneath the call span, which is never current while your code iterates a stream. Run-span opt-in is process-wide and sticky after the first opted-in wrapper or truthy SOLWYN_OTEL_SPANS at run entry. See Call spans and Run spans.
  • Opt-in Anthropic conversation IDs — anthropic_conversation_id=True or SOLWYN_ANTHROPIC_CONVERSATION_ID=true extends an Anthropic client's existing open_telemetry mapping with the active run ID, so native Anthropic spans carry gen_ai.conversation.id. Customer settings and conversation IDs are preserved, and the ID is never sent to Anthropic. Requires anthropic>=1.14; off by default. See Anthropic conversation IDs.
  • assert_trace_ingest_contract in solwyn.testing.contract posts sampled and unsampled trace-correlated events. See The contract pack.

Changed

  • Anthropic beta Messages are metered — client.beta.messages.create(...) is budget-checked and settled on sync and async clients, streaming and non-streaming, including the Bedrock, Vertex, and Foundry platform clients. Beta request fields (betas, context_management, compaction) pass through unchanged and are never recorded. A beta call fails over only to other Anthropic models in your fallback= chain; cross-provider entries are skipped. Migration: remove a beta.messages.create acknowledgment token — a stale token raises ConfigurationError. beta.messages.stream, .parse, .tool_runner, .count_tokens, batches, and the raw/streaming response mirrors stay unmetered. See Beta Messages.
  • Anthropic server-side compaction is counted — compaction usage, which Anthropic reports only in usage.iterations, is added to the settled input, output, and cache counts for streaming and non-streaming calls. token_details carries the compaction share as compaction_input_tokens, compaction_cached_input_tokens, compaction_cache_creation_5m_tokens, compaction_cache_creation_1h_tokens, and compaction_output_tokens, each omitted when zero, so calls without compaction send the same payload as before. Anthropic streams also settle the cumulative input and cache counts reported on the final message_delta. See Server-side compaction.
  • OpenAI Decisions is metered — native decisions.create(...) (openai>=3.26) is budget-checked and settled with text pricing on sync and async clients, using the requested model even when the response echoes a dated snapshot. Migration: remove a decisions.create acknowledgment token on native OpenAI clients. Azure OpenAI, compatible providers, the raw/streaming response mirrors, and the read-only admin.organization.usage.decisions report stay unmetered. See Decisions.
  • Background tasks no longer inherit the caller's context — async reporter and budget-lease tasks start in an empty context, so application instrumentation no longer attributes their work to the first caller's trace. See Async usage.
  • Newer provider SDKs are classified — openai 3.33–3.37 (audio.voices, audio.voice_consents, realtime.translations.connect and client_secrets, safety.cases, and more beta.agents and admin leaves), anthropic 1.15–2.3 (the organization and user_profiles administration trees, newer beta.organization.* operations, beta.messages.thread, and the open_telemetry option as metadata), together 2.41 and 3.0 (clusters, post_training, projects, beta.jig rollback, and the promoted top-level endpoints / models / organization with organization.usage.costs), and google-genai 2.25's voices / aio.voices. They are unmetered, follow on_unmetered, and need exact acknowledgment tokens in strict mode. Anthropic 2.x needs no wrapper change, and native Together chat stays metered on 3.0's new inference host. Together with the two leaves promoted to metered, these admissions move pinned CoverageFingerprint values. See Coverage controls and Surface coverage.

Fixed

  • Wrapped AnthropicBedrock and AnthropicBedrockMantle clients keep the caller's http_client on every provider call (sync and async), and AnthropicBedrock also keeps its aws_profile. A client configured with a named AWS profile could fail to resolve credentials, and a custom transport or proxy was bypassed. See Anthropic.
  • Runs in sync generators stepped in fresh contexts keep their attribution — with Starlette/FastAPI StreamingResponse, every call is attributed to the correct run and parent, including runs and detached activations wrapped in context managers or ExitStack. Scope exit releases the run's lease without raising when an outer run is active, run stops follow the generator's run, activations can exit across yields, and start_run() handles can finish from their owning generator in a later step. Recovery follows up to 256 stack frames; threads started inside a recovered step need an explicit detached activation, and scopes inside async generators remain unsupported. See Sync generators stepped in fresh contexts.
  • Strict mode no longer refuses client.timeout reads — on wrapped OpenAI, Anthropic, Azure OpenAI, Together, and OpenAI-compatible clients, numeric, None, and timeout-object values are preserved without raising UntrackedSpendSurfaceError, including raw clients copied with with_options(timeout=...) before wrapping. See Structural pass-through.

0.8.0 — 2026-09-21

The SDK no longer estimates cost during a control-plane outage, and every outcome it cannot settle now keeps its token bound instead of leaving a reservation for the sweep to refund. The outage estimate used a flat per-token rate that meant nothing once calls became multimodal and broke the rule that Solwyn Cloud owns pricing: the legacy per-call path now keeps a token-only tally of the calls it admits while Solwyn is unreachable and reports it on the next successful budget check. The reporter and the lease-release path gain fixed bounds, run-control lookup is constant time in a run's active streams, and the surface ledger catches up with openai 3.16.2, together 2.35, and google-genai 2.24. One public signature changed (BudgetExceededError) and one name was removed (solwyn.budget.DEFAULT_COST_PER_TOKEN). The wire-contract change is API-first: Solwyn Cloud has accepted uncounted_calls / uncounted_tokens on /budgets/check since 2026-09-17.

Changed

  • Behaviour change: fail_open=False fails closed on the per-call check path while Solwyn is unreachable — it used to admit calls against the last known dollar limit using a local per-token cost estimate, a ledger that started at zero on every outage and never included the spend the server had already counted, so it could not enforce the real limit. Now every call that no live budget lease covers raises BudgetExceededError until Solwyn is reachable again, including the first call of a run that holds no lease yet. The error carries budget_limit and current_usage of 0.0, budget_period="unknown", and your configured budget_mode (an alert_only client still raises); its receipt reports deny_source="local_enforcement" and deny_reason="control_plane_unreachable", and the SDK logs budget.fail_closed_unreachable at most every 30 seconds. Migration: to keep run-scoped calls metered through an outage, run them inside solwyn.run(...) with lease_enabled=True (the default), or set fail_open=True to admit and tally. A prior hard deny, a retained run stop, and a cached allow behave exactly as before. See When Solwyn Cloud is unreachable.
  • fail_open=True tallies the calls it admits during an outage — one call plus its input-token estimate per admission, replaced by the provider-reported total when the call settles (a media call with no token usage, or a stream abandoned before its usage chunk, keeps its estimate). The tally rides the next /budgets/check that reaches Solwyn as uncounted_calls / uncounted_tokens, both omitted when zero so an ordinary check is byte-identical to 0.7.0; Solwyn Cloud records it as an advisory gap, never as priced spend. It is kept for the next check on a 408, 409 or 429, any 5xx, a transport error or timeout, a breaker hold, or a cancellation, and cleared by any 2xx or any other 4xx (logged as budget.uncounted_report_dropped, at most every 30 seconds). It only rides a budget check: all-lease or allow-cache traffic never sends one, and a tally still unsent at process exit is lost — there is no exit flush. Lease-path tallies are unchanged and still ride renewals. See When Solwyn Cloud is unreachable.
  • Breaking for code that constructs BudgetExceededError directly: estimated_input_tokens: int is a required keyword and estimated_cost is now float | None, defaulting to None — it is set only from a server-supplied figure, which Solwyn Cloud does not supply today, so it is None on every SDK-raised error. Code that formats e.estimated_cost as a number must switch to e.estimated_input_tokens. See BudgetExceededError.
  • Unknown provider usage retains the authorized token bound — cancelling an async chat or Responses call after the provider SDK was invoked (including while it still waits for a connection-pool slot), interrupting a sync call mid-dispatch with KeyboardInterrupt, SystemExit, or another non-Exception exit, a failure while wrapping an already-open provider stream (including at a Responses stream() helper's entry), a stream whose streamed usage cannot be finalized, and a read timeout, 5xx, or protocol drop with ambiguous failover disabled all retire the reservation at its bound behind a possibly_succeeded error receipt, record no provider-breaker verdict, and re-raise the original exception. Under failover_idempotency="always" an ambiguous hop pins the reservation at its bound for the rest of the call. Proven pre-send failures, request-shaped 4xx refusals, and an interrupt that provably landed before the request (or during a Retry-After wait) still return unused authority. The conservative tally can exhaust a lease sooner under aggressive caller timeouts; it never invents output usage or cost, and each terminal's charge leaves on the run's next renewal or surrender. See When a call does not finish cleanly.
  • Lease releases are bounded and share one HTTP pool — each budget enforcer runs at most 4 release workers with at most 64 releases parked unsent, identical lease/holder/generation/spend payloads coalesce, a full queue abandons the new unsent courtesy release (release_counts["queue_full"]), parked work still unsent after six seconds expires (expired, shortened to close()'s 3-second drain), and worker-start failures count dispatch_failed. Releases reuse a dedicated pool separate from provider clients and the reporter; local pool/TLS failures count setup_failed and other local errors local_error without touching the shared control-plane breaker, and cancelled async workers count cancelled. On AsyncSolwyn the pool belongs to the loop that built it: close() must run there while it is alive, and a later loop rebuilds it. A burst of 128 finished runs used to start a thread and a TLS client per release. No configuration or wire change. See When a lease is handed back.
  • reporter_batch_size must be at least one — the constructor, SOLWYN_REPORTER_BATCH_SIZE, and direct reporter construction reject zero and negative values instead of accepting a batch that could never make progress. See Reporter settings.
  • Run-control lookup is constant time in the number of active streams — admission, the post-check, stream-handle acquisition, stop publication, clear, and release no longer scan a run's live handles; termination authority is one shared epoch per clear generation, so a stop is a single write every current watcher reads and the per-chunk abort check is a lock-free read. A stream that latched a stop keeps aborting and one that never latched is never latched by a later stop, by construction. No public API, configuration, or wire change. See Run control.
  • 816 new provider-SDK rules are classified — audited against openai 3.16.2 (openai 3.14's beta.agents.* tree and live.*, openai 3.16's webhooks.* management with the webhooks.event_types namespace), together 2.35 (beta.endpoints.rollouts.*), and google-genai 2.24 (environments.files.upload, and the inert credentials properties as metadata). Namespaces are guarded, leaves are unmetered spend acknowledgeable by their exact dotted path, raw- and streaming-response mirrors are raw_response-scoped escapes; no existing rule moved and nothing was promoted to metered. Before this release these paths resolved to unknown and followed on_unmetered, as they still do. A CoverageFingerprint pinned on openai 3.8 moves in guarded_namespaces, untracked, and scoped_escapes once you are on openai 3.16.2 — re-capture it then. See Surface coverage.

Fixed

  • A provider exception with an unusual class name can no longer cost a metadata batch or hide the provider's error. failover_error_class is normalized before the event is built — leading characters up to the first ASCII letter stripped, every other character outside [A-Za-z0-9_.] replaced by _, cut to 64 characters, omitted when no letter remains — so grpc's _InactiveRpcError is reported as InactiveRpcError instead of making Solwyn reject the whole ingest batch with a 422, and a class name over 64 characters no longer raises a ValidationError in place of the provider's exception. The error receipt is now best-effort: if one cannot be built or enqueued the SDK logs call.error_receipt_failed, still ends the reservation, and re-raises the provider's original exception. See Privacy.
  • A cancelled recovery attempt no longer strands the provider's half-open probe. Cancelling a recovery attempt, abandoning a Responses stream() manager before entry, or a request-shaped refusal at manager entry used to leave the breaker's single probe held, so no later attempt could prove the provider healthy. Each admitted attempt now owns its probe until a health verdict or an explicit hand-off to a manager or live stream; stale cleanup cannot clear a successor's probe, a cancelled Responses helper entry no longer records a false breaker failure, and malformed streamed usage retires ownership without a false verdict. See Circuit breaker.
  • Cancelling a lease grant behind a predecessor release no longer forces later same-run calls onto legacy budget checks. Grant-slot cleanup now runs even when the fence wait is cancelled or probe cleanup raises, so the run's next call re-grants instead of paying the per-call /budgets/check for the rest of the process. If the bounded wait for an old release expires while that request is still active, the call uses the per-call check once and the old request keeps its slot until it ends.
  • A steady stream of successful confirms can no longer starve metadata ingestion. Each reporter round now handles at most min(reporter_batch_size, reporter_max_queue_size) standalone confirms and the same number of settlement confirms (50 each by default), then a bounded snapshot of ready metadata batches; productive rounds continue immediately, held and retrying heads keep their FIFO parking, and a settlement's confirm still precedes its metadata transfer. reporter_max_in_flight remains an event-send guard, not a throughput setting. See Fairness between confirms and metadata.

Removed

  • solwyn.budget.DEFAULT_COST_PER_TOKEN and the enforcer's local dollar ledger. Nothing in the SDK multiplies tokens by a price. The top-level solwyn package exported neither, so from solwyn import ... statements are unaffected.

0.7.0 — 2026-09-05

A run's budget lease is handed back the moment the SDK stops using it — at scope exit, on a revoked renewal, and on an operator stop — instead of waiting for close() or the server deadline, so the float returns to the project while the process keeps running. Every event of a lease-funded call now names its lease, letting Solwyn Cloud count that call once even when its confirmation is lost. solwyn.testing.FakeControlPlane mirrors both, and the surface ledger catches up with openai 3.8, anthropic 1.4, and google-genai 2.22. No existing name was removed or renamed and no signature changed; the only additions are the two names below. Wire-contract changes are API-first: Solwyn Cloud accepts every field below before this SDK releases.

Added

  • MetadataEvent.lease_id — every event of a lease-funded call — the success event, a failed-over attempt's error event, an ambiguous abort, an aborted stream's partial settlement — carries the server-minted id of the lease whose grant admitted it, the same id its confirmation carries. It is omitted from the wire when the call was funded by a per-call reservation (outside a run, in a tagged run, with per-call solwyn_tags, on a media or embedding surface), admitted from the allow cache, admitted uncounted during an outage, or denied, so payloads for those calls are byte-identical to 0.6.0. A renewal or a fresh grant landing while a call is at the provider never changes the id that call reports. See Privacy.
  • FakeControlPlane.released_leases — the lease ids a surrender actually released, alongside the existing lease_surrenders record of what the SDK sent, so a test can tell a release that landed from one the fence refused. See Inspecting what the SDK sent.

Changed

  • Leases are handed back as soon as the SDK stops using them — exiting a with solwyn.run(...) block (normally or on an exception), RunHandle.finish(), a renewal answered ineligible or denied, a lease block that cannot be read, and a server run-stop directive each surrender the run's lease immediately, off the calling thread (a solwyn-lease-release daemon thread, or a task on AsyncSolwyn); a release that cannot be dispatched — no running event loop, thread exhaustion, interpreter shutdown — is parked and rides close(). A handle.activate() exit on a create_run(...) handle deliberately keeps the lease, because a detached identity is re-entered; a renewal 404 / 409 and a local expiry have nothing to release. Work that outlives its scope with the run id still bound pays one blocking grant on its next call, fenced behind the release of the lease it replaces (at most 6 seconds) so the server sees the replacement after the release. An inner run releases only its own lease. Previously a lease the SDK had stopped using kept its float reserved until close(), the exit hook, or the server deadline. See When a lease is handed back.
  • Surrender is bounded at 3 seconds and retried once on timeout — up from 1 second with no retry. A refusal or transport failure is still not retried, an open control-plane breaker skips the release, and close() bounds the whole lease drain — releases still owed plus leases still held — at the same 3 seconds; the interpreter-exit budget is unchanged at 2 seconds. Because a scope exit now releases before the reporter has necessarily flushed, a surrender can reach Solwyn before the call's confirmation; the confirmation still settles, and the recorded spend is the same either way. See Shutdown.
  • Breaking for test suites that pin the double's wire shapes — FakeControlPlane answers /api/v1/metadata/ingest with a third lane, duplicates (index, reason of call_id or legacy_key, call_id), that partitions the batch with ingested and rejected; reject_ingest raises RuntimeError when a scenario names a dedup-skipped index, and its count= form draws from fresh events only. The surrender fence accepts the predecessor of a terminal successor and any generation of a stopped run's lease, so a test that pinned a 409 there now meets 200, and a stopped run does surrender — a test asserting plane.lease_surrenders == [] after stop_run no longer holds. assert_receipt_ingest_contract posts a third, lease-tagged event, so it fails against a server that predates lease_id. The SDK itself still reads only rejected from the ingest body. See Testing budget enforcement.
  • 795 new provider-SDK surfaces are classified — audited against openai 3.8 (safety.alerts.*), anthropic 1.4 (the beta.organization.* admin tree, beta.webhooks.parse_unverified, raw and streaming messages.batches.results), and google-genai 2.22 (environments.files.*). Namespaces are guarded silently and their leaves are unmetered spend under your on_unmetered posture, acknowledgeable by exact path; no existing rule moved, so nothing that was allowed or refused before changes. A CoverageFingerprint pinned under 0.6.0 differs in guarded_namespaces, untracked, and scoped_escapes once you are on openai 3.8, anthropic 1.4, or google-genai 2.22 — re-capture it then. See Surface coverage.

Fixed

  • A renewal or release thread that fails to start no longer breaks close() — the thread is registered only after a successful start, closing a race where a concurrent close() could join a thread that never ran; a release whose thread cannot start is re-parked and sent at close().

0.6.0 — 2026-08-24

The SDK grows from a budget gate into a control plane for agent runs. A run can now be stopped from the dashboard — or by the SDK's own content-free velocity detector — and the stop survives control-plane outages, aborts open streams at the next chunk, and leaves a denial receipt that is never lost. Failover becomes cost-aware, native OpenAI and Azure OpenAI Responses calls are metered, wrappers pass isinstance so agent frameworks admit them, every provider capability your code reaches is classified under a posture you choose, Anthropic 1.x is supported on httpx2, and solwyn.testing.FakeControlPlane exercises all of it with zero network. Wire-contract changes are API-first: Solwyn Cloud accepts every field below before this SDK releases.

Added

  • Agent-run stops raise RunStoppedError — an operator pressing Stop on the dashboard's Agents tab makes Solwyn Cloud deny the run's next budget check or lease renewal with a version 1 run_control terminate directive, and the SDK raises RunStoppedError on the next intercepted call. The exception inherits from SolwynError, not BudgetExceededError, so an agent loop's budget-denial handler cannot swallow and retry an explicit stop; it carries only the structural agent_run_id, reason, and source (server or local_velocity). A stop is retained per run through outages regardless of fail_open, is never softened by alert_only, refuses lease authority, and reaches a leased run through its renewal channel. It governs future dispatch — a non-streaming request already in flight completes — while streams stop at the next raw provider-chunk boundary: that chunk is pulled and discarded, prior usage settles exactly once as a partial success, and the provider stream is closed. Read and clear the retained state with current_run_terminated(), run_termination(run_id), and clear_run_termination(run_id); the registry is a 256-entry LRU that never guesses from fingerprints. A directive echoed for the wrong run is treated as contract drift on one call, credits the control-plane breaker, and logs a distinct ERROR. See Run control.
  • Content-free local velocity detection — seven velocity_* / SOLWYN_VELOCITY_* settings control the mode (warn by default, deny, or off) and the thresholds of three per-run rules: repeat_size (the same model with the same-sized prompt, repeatedly), monotonic_growth (prompts growing steadily), and the advisory-only rate_acceleration. Detection runs in-process on token counts and timing, never on content; under deny the first two rules stop the run locally, and a server allow never lifts a local stop. See Local velocity detection and Velocity settings.
  • Denial receipts that are never lost — every refused call reports a budget_denied event carrying deny_source, deny_reason, denied_by_period, estimated_output_bound, velocity_flags, and, on aggregates, receipt_aggregate_count and receipt_pricing_input_tokens. A receipt that would otherwise be dropped — overflow, ingest rejection, retry exhaustion, shutdown — folds by pricing-compatible identity (including the reason and period, so a run's run_stopped and monthly evidence never merge) and replays as one aggregate_replay event after delivery recovers. Folded receipts are not counted as drops; only a full aggregate table loses one, counted as receipt_fold_overflow. See Denial receipts and aggregate replay and Privacy.
  • A zero-network control-plane test double — solwyn.testing.FakeControlPlane plugs into the new caller-owned control_plane_transport seam, shared by normal operation, fork recovery, interpreter-exit delivery, and lease surrender, and speaks the production wire models. It scripts transport outages, endpoint refusals, magic-model verdicts (solwyn-test/deny, deny-alert, deny-tag, deny-stopped, runaway, kill, lease-ineligible), operator kills (stop_run, clear_stop, misroute_stops), ingest rejections, reservations, and the complete lease lifecycle, and records every request the SDK sent, including denial_receipts and aggregate_replays. It never prices anything. A reusable solwyn.testing.contract pack is dogfooded against both the double and the live API, and solwyn.testing.pytest_plugin provides explicitly opt-in, function-scoped fixtures — never automatic registration. See Testing budget enforcement.
  • Type-transparent wrappers — Solwyn(client) and AsyncSolwyn(client) report the wrapped provider class through __class__, so isinstance(wrapper, OpenAI) is True and frameworks admit the wrapper, while type(wrapper) stays truthful. Public attribute writes and deletes forward to the provider client; copy.copy and copy.deepcopy return the same wrapper; pickling raises with guidance to construct a fresh wrapper in the target process. Passthrough reads still cross the coverage guard. See Type transparency.
  • Detached run identities for framework callbacks — start_run(...) opens a scope and returns a RunHandle whose finish() closes it; create_run(...) snapshots a stable run id, parent, and inherited tags without changing the current context, and handle.activate() binds that identity around provider work in any task or thread, as often as needed. finish() fails loud while an activation is live. See Detached run handles.
  • Framework integrations — tested, offline-smoked recipes for the OpenAI Agents SDK (a wrapped AsyncSolwyn default client plus recipe-local model and provider adapters; no module ships), LangChain and LangGraph (solwyn[langchain] adds the content-free SolwynRunScopeHandler; the exact raw-response shim admits basic non-streaming invoke / ainvoke and two-node graphs), and CrewAI (solwyn[crewai] adds the structural SolwynEventListener; native LiteLLM stays attribution-only, and a narrow custom-BaseLLM recipe crosses a wrapped client). Every integration module is privacy-firewall-enforced, and scheduled smokes re-resolve current framework releases. See Framework integrations.
  • Native OpenAI and Azure OpenAI Responses calls are metered — sync and async responses.create(...), responses.parse(...), and the responses.stream(...) helper use one primary-only path: chat-only defaults are stripped, caller arguments win, and preflight and dispatch see the same mapping. Usage settles from the response or the stream's terminal event; an entered stream abandoned early, or a create/parse with missing or zeroed usage, settles a marked request-length estimate and keeps its lease reservation. background=True, a streaming parse, and extra_body overrides of model, input, instructions, max_output_tokens, or stream are refused with ConfigurationError before any I/O; the existing-response retrieval overload stays raw. Azure is the one compatible profile admitted. See The Responses API.
  • Explicit provider identity pins bypass auto-detection — provider="openai" (or a fallback tuple's fourth element) selects the named adapter without inspecting base_url, keeping native metering — including Responses — behind corporate gateways and local proxies. A pin never translates dialects or replaces the client: construction validates the client family and sync/async mode, rejecting mismatches with ConfigurationError(field="client") and unknown names with field="provider". See Explicit provider identity.
  • CostPolicy consumes server price hints — every budget check opts into price_hints_version: "1", and the request-scoped hints apply only to the call they were priced for. When the policy serves a cheaper healthy provider ahead of a healthy primary, the metadata event reports failover_reason: "cost_routed" — only when the served hint is strictly below the primary's (or the primary carries no hint), so a custom policy that fronts a pricier provider is still labelled circuit_open. See Cost-aware routing.
  • Strict pre-call coverage controls — clients classify and guard the whole reachable public provider-client graph. on_unmetered="raise" / SOLWYN_ON_UNMETERED=raise refuses untracked or unknown capabilities before provider I/O with the exported UntrackedSpendSurfaceError, which names the exact refused capability and its acknowledgment token; warn remains the default and allow the explicit unrestricted posture. acknowledge_untracked / SOLWYN_ACKNOWLEDGE_UNTRACKED accept exact terminal tokens only — namespaces, wildcards, tracked, blocked, and unsupported leaves are rejected at construction — with audio.speech.create:gpt-4o-mini-tts for the conditional TTS exception. coverage(client) returns a deterministic, content-free, sans-I/O CoverageReport you can pin with expect(...) so a provider-SDK upgrade fails a test instead of a budget. See Coverage controls.
  • Privacy-safe advisory reporting of untracked surfaces — on by default. Unacknowledged warn / allow observations are reported off the hot path, at most once per surface every fifteen minutes, as a structural payload: the dotted surface path, provider, client shape, mode, rule kind, scope, posture, approximate counts, timestamps, and random identifiers — never model names, arguments, prompts, or responses. It adds no budget check and no cost event, and report_untracked_surfaces=False / SOLWYN_REPORT_UNTRACKED_SURFACES=false turns the channel off without changing local behavior. See Advisory reports and Privacy.
  • Anthropic 1.x on httpx2 — Solwyn never imports httpx2; it recognizes the stack by identity. Per-hop timeouts are delivered as a native httpx2.Timeout when the client's own timeout class is identity-proven (so Anthropic's x-stainless-read-timeout header carries the numeric bound), and as a granular four-tuple otherwise. Anthropic 1.0's promoted-stable files and skills surfaces are classified as unmetered spend under the ordinary on_unmetered posture. See Anthropic.
  • New configuration — on_unmetered, acknowledge_untracked, report_untracked_surfaces, and the seven velocity_* fields, each with a SOLWYN_* environment variable, plus the constructor-only control_plane_transport. See SolwynConfig.

Changed

  • The budget allow cache is bounded and hint-aware — a 16-entry LRU keyed by provider, model, fallback chain, and modality, with the existing budget_check_cache_ttl window. A hit replays only its own entry's hints; run-scoped and tagged calls never read it. CostPolicy warns once only when a check carries no hints (null), not when the server explicitly clears them with {}.
  • Breaking only for consumers of private wrapper attributes — Solwyn-owned state now lives under _solwyn_*. The former _client, _budget, and _reporter no longer expose Solwyn internals; every non-prefixed private name belongs to the wrapped provider client. Public APIs are unchanged.
  • Breaking (pre-launch): the metered Responses leaves are no longer acknowledgeable — responses.create, parse, and stream are tracked and are rejected as acknowledgment tokens; the still-unmetered responses.retrieve remains the example.
  • Untracked capabilities warn once by default instead of passing silently — files, batches, moderations, models.list, and everything else Solwyn does not meter now log one warning per surface per process. Guarded namespaces keep descendants inside the same posture decision. Strict mode is a cooperative pre-call guard, not a sandbox: retained raw clients, private wrapper state, acknowledged scoped raw escapes, and native behavior on returned provider objects stay outside its boundary. See Surface coverage.
  • Over-limit provider paths keep the local posture — a public path too long or deep for the advisory wire is counted and warned about locally and never sent externally; malformed paths still fail closed.
  • run_stopped denials stay sticky only for their run — a control-plane outage can no longer replay a dashboard stop against unrelated run ids, and BudgetExceededError.budget_period now carries the actual Cloud or lease label (agent_run, tag, model, provider, or a period), falling back to unknown only when none was supplied.
  • Breaking for anyone passing inf: failover timeouts must be finite — failover_total_timeout and failover_hop_read_timeout reject booleans, NaN, and ±inf at construction; float("inf") was previously accepted and produced an unbounded window or hop read. The hop read bound must still be positive; a zero total timeout remains accepted. See Failover timeouts.

Fixed

  • A Responses stream-helper entry failure is classified instead of always blaming the provider. The manager sends its request at __enter__, so that failure now runs the same dispositions the candidate walk uses: a request-shaped 4xx records no breaker failure, while failover and post-send-ambiguous errors keep the breaker verdict. Previously a repeated 400 on responses.stream(...) could open the breaker and block all traffic to a healthy provider.
  • Compatible-provider Responses streams without readable usage hold their lease floor — a settlement that falls back to a length estimate is treated as unmeasured, so a run lease trues up at its reserved bound instead of re-lending output allowance the response already spent.
  • Closing a Responses stream helper before entering it releases its reservation — no provider request was dispatched, so no phantom confirm, breaker success, or latency sample is recorded.
  • extra_body={"stream": ...} is refused on metered Responses calls — the OpenAI SDK merges extra_body after named arguments, which would desync Solwyn's streaming mode from the dispatched request.
  • Anthropic 1.x transport failures are classified instead of failing fast — an httpx2 transport error is dispositioned exactly like its httpx twin and at the same position, ahead of any attached status: connect and pool failures fail over; read, write, and protocol failures stay post-send ambiguous.
  • The solwyn.testing contract probe opts into price hints and validates the served map — every key must be a known ProviderName (an unknown key makes the whole check response unparseable, so the SDK would fail open with no reservation) and every value a finite number; {} and null remain valid.

Removed

  • Solwyn.update_price_hints / AsyncSolwyn.update_price_hints and the client-wide hint store — price hints are request-scoped and supplied by the server's budget response.

Known limitation

  • Lease-backed solwyn.run() calls carry no price hints, so CostPolicy keeps configured provider order for those calls — and fires its once-per-process no-hints warning — until lease grants carry hints.

0.5.0 — 2026-08-07

Spend attribution becomes first-class: clients carry default tags, nested run scopes inherit and refine them key by key, one immutable per-call snapshot feeds both budget admission and spend events, and nested runs report their immediate parent run. Wire-contract changes are API-first: Solwyn Cloud accepts every field below before this SDK releases.

Added

  • Client default spend tags — Solwyn(..., tags={...}) / AsyncSolwyn(..., tags={...}) or SOLWYN_TAGS apply to every intercepted call from the client. The environment value is comma-separated key=value entries, split at the first =; values containing commas use the constructor mapping. Run-scope tags override client defaults key by key, and per-call solwyn_tags= has the highest precedence. See Tags.
  • Budget admission observes the call's tags, and tag-cap denials stay selector-scoped — a tagged call's /budgets/check carries the same immutable tag snapshot its spend event reports, which is what a tag-scoped budget decides on. A denial with denied_by_period == "tag" denies only traffic matching that selector and never creates project-wide or run-wide sticky authority. Tagged calls always take a fresh budget check, bypassing the allow cache and the run lease path. See Tags and budget admission.
  • Nested runs report their immediate parent — spend events from a nested solwyn.run(...) scope carry parent_agent_run_id; root runs omit the field. Parent context restores after normal exits and exceptions, including across concurrent asyncio tasks. See Nesting.
  • solwyn.current_run_context() returns the active RunContext(id, name, tags) with a defensive copy of the scope's tags. RunContext and the attribution bounds TAGS_MAX_KEYS, TAG_KEY_MAX_LENGTH, and TAG_VALUE_MAX_LENGTH are package exports.

Changed

  • Nested solwyn.run(...) scopes inherit tags additively by default — a child keeps all non-conflicting outer tags and overwrites only keys it supplies. inherit_tags=False starts a fresh tag scope; exiting either form restores the exact outer context.
  • A combined tag map over 10 keys clamps without aborting the live call — per-call keys are kept first, then scope keys, then client defaults, preserving insertion order within each layer; each overflowing capture emits one SolwynTagsClampedWarning, exported from the package root, and drops the lower-priority excess from that event while the provider request continues. A single mapping over 10 keys still raises. See Bounds, validation, and clamping.
  • Tag keys and values containing NUL are rejected eagerly, mirroring the control plane's storage and selector constraints, so an invalid tag cannot turn a budget check into an outage failure.

0.4.0 — 2026-07-28

The control plane comes off the hot path. A run now takes one token lease instead of asking permission before every call, settlement stops holding your provider response hostage, and spend telemetry is delivered at least once — across outages, forks, and interpreter exit. Failover timeouts split into a window and a per-hop read bound, so a slow generation is no longer cut into ambiguous spend.

Added

  • Run-scoped budget leases — a token-billed call inside a solwyn.run(...) scope used to pay a blocking budget round-trip to Solwyn before every provider request. The run now takes one server-granted lease, draws it down in memory, renews it in the background ahead of need, and hands it back when the run is done. The shape is DHCP's, for the same reason: authority is delegated for a bounded window so the client keeps serving without asking permission per call. A lease is denominated in tokens, never dollars — the server folds price into the grant, and the SDK still performs no pricing math. Each call reserves its input estimate plus the largest effective output cap across every configured hop (honoring per-call over per-entry over global precedence, and each provider's own cap spelling), then trues that reservation up to actual usage at settlement. Renewal is driven by demand rather than a timer — at 75% depletion or the refresh deadline — so an idle run costs nothing. Non-run calls, non-text modalities, media calls, and models outside the lease's declared set take the per-call check path automatically. Disable entirely with lease_enabled=False. See Run-scoped leases and Privacy.
  • A defined outage ladder, so no deny ever traces to unreachability — with the grant spent and Solwyn reachable, a call falls back to a per-call check (an empty wallet is not a refusal). With Solwyn unreachable, it draws on the lease holder's apportioned slice of real remaining headroom, admitted with a warning and still metered. Only when that is genuinely exhausted does your budget_mode decide. Past the lease deadline with Solwyn still down, your fail_open posture picks the floor: fail_open=True admits calls uncounted and tallies every one for the next successful renewal to report, while fail_open=False meters against the freshest known remainder and denies at your configured mode. Uncounted episodes announce themselves — lease.uncounted_entry on entry, then lease.uncounted_continuing at most every 30 seconds. See When Solwyn Cloud is unreachable.
  • failover_hop_read_timeout (default 600.0) — each hop's read/write bound, now decoupled from the failover window. 600.0 matches the openai and anthropic SDKs' own read/write default, so a wrapped call's read bound never fires earlier than the unwrapped SDK's would. Constructor-only (deliberately no environment variable) and governed by the same plan entitlement as the other failover knobs, which is now a closed set of eight fields rather than seven. See Failover timeouts.
  • A control-plane circuit breaker — a Solwyn outage is now discovered once per client rather than re-paid as a timeout on every call. One breaker guards both the budget check and the settlement path, applying your configured posture instantly instead of waiting. It is a separate health domain from your provider breakers, never appears in breaker state reports, and treats a read-only-key refusal as a success (Solwyn responded). Tuned by control_plane_failure_threshold and control_plane_recovery_timeout. Breaker log lines now name their domain: Circuit breaker [control-plane] opened due to failures.
  • A build-time warning for unbounded Bedrock reads — Solwyn cannot bound a Bedrock hop per call, so a botocore Config(read_timeout=None) is the one shape neither Solwyn nor botocore will ever bound. Building such a client now warns. Detection is defensive: an unreadable or absent config reads as bounded. See Bedrock.
  • New configuration — lease_enabled, lease_output_bound_default, budget_check_timeout, control_plane_failure_threshold, control_plane_recovery_timeout, breaker_report_heartbeat, reporter_max_send_attempts, reporter_retry_backoff_base, reporter_retry_backoff_cap, and reporter_shutdown_deadline, each with a SOLWYN_* environment variable, plus the constructor-only failover_hop_read_timeout. See SolwynConfig.

Changed

  • Settlement moved off the caller's thread — non-streaming chat completions and the entire media lifecycle (embeddings, images, audio, video) used to settle with a blocking confirm request on your thread after the provider had already answered, withholding the response until Solwyn's round-trip returned. Settlement is now built without I/O and enqueued with its metadata event as one ordered item — the path streaming completions already used. You get the provider response without waiting on Solwyn. See Spend delivery.
  • Spend telemetry is delivered at least once — confirms, settlements, and metadata batches were previously dropped on their first failed send. They are now retried with bounded exponential backoff. A transport error or an HTTP 408/429/5xx is transient and retried; every other status is terminal, so a poison item can never wedge the queue head. The server deduplicates on an idempotency ledger, so the SDK retries freely and never deduplicates client-side. Queues drain strictly FIFO, so later spend can never be confirmed ahead of earlier acknowledged spend. During a Solwyn outage a settlement is held for a later cycle rather than dropped, and if a settlement is ultimately rejected its paired metadata event is still delivered — ingest is the durable record of spend.
  • Undeliverable spend is counted and loudly logged, never silently dropped — queue overflow, retry exhaustion, terminal statuses, per-event ingest rejections, shutdown-deadline expiry, and enqueue-after-close all increment a counter surfaced by reporter.spend_events_dropped. The first drop logs immediately; after that at most one aggregated line per 60 seconds, so a sustained outage reports its loss without flooding logs. See Undeliverable spend.
  • Queued spend survives interpreter exit, and reporters survive fork() — a process exiting without close() used to discard everything queued; an exit hook now flushes each live reporter and surrenders held leases on a wall-clock deadline, so an unreachable Solwyn can never hold up process exit. Separately, threads, locks, and HTTP clients do not survive fork(), so a forked child inherited a dead flush thread and never delivered its settlements — the SDK now rebuilds them on the child's next enqueue, abandoning (never closing) the parent's sockets and deliberately keeping fork-duplicated items, since the server deduplicates.
  • close() is bounded by one shutdown deadline — reporter_shutdown_deadline (default 5.0) is now shared across the worker join, the final flush, and the breaker-report cycle, so shutdown against a black-holed control plane no longer pays a serial per-request timeout chain. It is a true wall-clock bound: the final flush runs off the closing thread, so a slow-drip response cannot hold close() open. Work still queued at the deadline is counted and dropped rather than requeued into a queue nothing drains.
  • The async reporter auto-starts on first enqueue — AsyncSolwyn previously flushed only after an explicit start(), which async with performs for you. Constructed without async with, it queued events and settlements silently until close(), drifting server-side spend tracking. The flush loop now starts on the first enqueue when a running event loop is present; with no running loop the item stays queued and one warning is logged per reporter. Enqueueing never raises — it sits on the LLM call path. See Async usage.
  • The failover window no longer caps an in-flight hop's read — failover_total_timeout (default 30.0) is now purely the failover window: the budget pre-flight, each hop's connect/pool slice, Retry-After sleeps, and advancement between hops. Reads are bounded separately by failover_hop_read_timeout. The old behavior cut a slow-but-connected provider at 30 seconds and re-raised it as APITimeoutError — but a read timeout is post-send ambiguous, and under the default failover_idempotency="safe" it re-raises without failing over. That cut therefore bought no failover; it only converted legitimately slow generations (reasoning models, large max_tokens) into ambiguous spend. Because window expiry still gates advancement between hops, at most one hop per call can consume the full read bound.
  • Two providers cannot be bounded that way — google-genai supports only a single whole-request timeout, so a google hop receives the read bound as its whole-request timeout and a google pre-send hang can exhaust the failover window without failing over (Google Gemini). boto3 has no per-call timeout override at all, so a Bedrock hop is governed entirely by your botocore Config (Bedrock).
  • The budget pre-flight timeout dropped to 1.0s (budget_check_timeout, was an effective 5s). That request gates the caller's hot path, and the control-plane breaker now caps repeated discovery of an outage.
  • The openai extra no longer installs tiktoken — pre-call token estimation is now always the length-based heuristic, which is what a conservative budget pre-flight needs. Exact tokenization was never used for billing, and post-call counts remain exact because they are read from the provider's response. See OpenAI.
  • Breaker reports are sent when a provider's snapshot changes — state, failure count, or success count — with a periodic full refresh governed by breaker_report_heartbeat (default 60.0 seconds), rather than on every cycle. A failed send leaves that provider due for the next cycle, and close() forces a final snapshot.
  • call_id pins the canonical UUID text form on the wire, matching what the API's idempotency ledger has required since it landed. The wrapper has only ever emitted that form, so nothing it sends changes. See Privacy.

Fixed

  • A connect or pool timeout wrapped by the provider SDK now fails over. Both openai and anthropic wrap the entire httpx.TimeoutException family in APITimeoutError, so a provably pre-send ConnectTimeout reached classification wearing the same class name as a post-send read timeout — and was treated as ambiguous, taking the whole call down instead of failing over to a healthy provider. APITimeoutError is now classified by its chained cause, the way APIConnectionError already was.
  • Server-pushed failover tuning is snapshotted once per call. A directive landing mid-call could leave that call running on a torn mix of old and new tuning — for example the new total timeout paired with the old idempotency mode. Each call now captures one immutable snapshot and consumes only that. See Plan-scoped tuning entitlement.
  • A media call whose failover window expired during the budget pre-flight no longer starts provider I/O, and releases its reservation — matching the chat path.
  • Output-cap alias precedence now matches dispatch on every provider hop, so a per-call cap beats provider-entry and global defaults even when one layer spells it max_tokens and another max_completion_tokens. Lease reservations therefore cannot silently use a lower-priority, larger cap.
  • Breaker-report writes now recognize read-only keys. The breaker-report request was the only Cloud write not routed through the one-time read-only-key diagnostic, so a read-only key produced a warning per provider on every reporter cycle, the exact noise that diagnostic exists to collapse. See Troubleshooting.
  • Post-success bookkeeping is fail-soft. Usage, region, and service-tier extraction now degrade on an adapter raise — usage to a flagged estimate, region and tier to omitted — instead of destroying a paid provider response. A call whose usage is entirely unmeasurable settles its lease at the reserved bound rather than crediting the untouched-looking output allowance back, which would re-lend authority a paid response already consumed.
  • Budget checks distinguish unparseable success bodies from transport outages. A 2xx with an unreadable body now logs budget.check_response_unreadable at ERROR and records breaker success (server contract drift), distinct from a transport failure.

Eleven new configuration fields — ten with SOLWYN_* environment variables plus the constructor-only failover_hop_read_timeout — all with defaults that preserve existing behavior for non-run traffic. Leases are on by default for eligible run-scoped calls; set lease_enabled=False to keep the per-call check path everywhere.

0.3.0 — 2026-07-16

Attribution and enforcement get finer-grained: agent runs carry labels you author and can be capped individually, circuit-breaker health reaches the dashboard, and custom failover tuning becomes a plan entitlement — one new configuration field, no breaking changes.

Added

  • Per-run budget caps — every pre-flight budget check made inside a solwyn.run(...) scope now carries the run's stable agent_run_id, so a budget can cap an individual run rather than only the project. Caps are server-enforced and configured in Cloud — there is no cap argument on run(); the SDK stamps the run id on the check and enforces the answer, raising the same BudgetExceededError in hard_deny mode. Run-scoped checks bypass the allow cache, so every call inside a scope performs a real check, and an authoritative hard deny is remembered per run id — preserved rather than failing open if Cloud then goes unreachable. A preserved deny is never silent: each call it applies to logs a WARNING on the solwyn.budget logger naming the usage and limit (Cloud API unreachable; preserving prior hard deny: $99.50/$100.00 used), so a sustained outage under a hard deny stays visible for its whole duration rather than announcing itself once. The same holds for the older global project-period deny. See Agent Runs and Logging.
  • Customer tags on runs and calls — attach your own key/value labels for cost attribution and dashboard filtering, per scope via solwyn.run(name, tags={...}) or per call via the reserved solwyn_tags={...} keyword, which the SDK strips before the request reaches the provider. The merge is shallow and per-call keys win; nested scopes replace rather than merge. Bounds are 10 keys across the merged set, keys 1–64 characters, values 0–256 — and violations are rejected, never truncated, raising before the budget check and before provider dispatch. Tags are the single deliberate exception to the zero-content guarantee: free-form text you author, transmitted as provided, never derived from your prompts — so never put prompt text, PII, or secrets in one. See Agent Runs and Privacy.
  • Circuit-breaker state reporting — the SDK periodically snapshots each provider's breaker and reports it — provider, state, failure and success counts, snapshot time, and a per-instance SDK id — giving the dashboard fleet-wide provider-health visibility. Advisory and one-way: Cloud snapshots never drive admission, state is never shared between instances, and every failover decision stays in-process. Reports ride the background reporter off the request path, never blocking a call, and begin only once a successful budget check has established the project. Disable with breaker_reporting_enabled=False or SOLWYN_BREAKER_REPORTING_ENABLED=false — the only new configuration field in this release. See Provider Failover, Privacy, and SolwynConfig.
  • Plan-scoped failover tuning entitlement — each budget check opts into a versioned failover directive, and Solwyn Cloud may answer with one governing a closed set of seven fields: the four failover knobs and the three circuit-breaker parameters. An absent directive is a no-op that retains your tuning, true (re)applies it, and false applies SDK defaults in its place — reversible in both directions, never a one-way ratchet. Strictly advisory: provider order never changes, breakers keep their identity and accumulated health state, a failover_total_timeout change preserves the original call start rather than restarting the clock, and calls never fail for lack of a directive. Suppressed tuning logs one WARNING per client instance, and only when your tuning actually differs from the defaults. See Provider Failover.
  • OpenAI prompt-cache write extraction — usage.prompt_tokens_details.cache_write_tokens (Chat Completions) and usage.input_tokens_details.cache_write_tokens (Responses API) are now extracted and reported as cache_creation_5m_tokens. OpenAI's cache writes carry a 30-minute default/minimum TTL, not 5 minutes — the field name is a wire-contract artifact mapping OpenAI's writes onto the existing bucket, not a claim about its TTL; cache_creation_1h_tokens stays 0 for OpenAI. Independent of cache reads, no opt-in or configuration, and unusable values degrade to 0 rather than raising. See OpenAI.
  • Read-only key diagnostics. When Solwyn Cloud refuses the SDK's writes because the configured key is read-only, the SDK now recognizes that structured response and logs one ERROR per process naming the cause, instead of a stream of generic Cloud-API warnings. Detection is exact: other 401/403 responses still surface as the ordinary warnings. Reporting is dropped, and budget checks fail open on the default fail_open=True, so your provider calls keep working while enforcement and attribution do not. See Troubleshooting.
  • UnsupportedSurfaceError in the package root — from solwyn import UnsupportedSurfaceError now works, and the class joins every other exception in the package's __all__. It shipped in 0.2.0 as a deep import only; the addition is additive, so from solwyn.exceptions import UnsupportedSurfaceError keeps working. See Exceptions.

One new configuration option, breaker_reporting_enabled. No breaking changes: tags is omitted from the wire entirely when you set none, so payloads for untagged calls are unchanged.

0.2.0 — 2026-07-11

The SDK goes multimodal: embeddings, images, audio, and video are now intercepted, budget-checked, and priced with the same wrapper-not-a-proxy privacy boundary as chat — quantities and selectors leave your process, never content.

Added

  • Embeddings interception — embeddings.create (OpenAI dialect, native Together) and models.embed_content (Google) are budget-checked and recorded as cost events with modality embedding, priced from input tokens; Google exposes no usage on embeddings, so its counts are length-estimated and flagged is_estimated. See Surface coverage.
  • Image interception — images.generate and images.edit (OpenAI, compat, native Together) and models.generate_images (Google Imagen). Token-billed image models price from usage token buckets; per-image endpoints return no usage, so billing is request-derived (image count × per-image rate) with the count, resolution, and quality selectors measured locally. See OpenAI and Google Gemini.
  • Audio interception — audio.transcriptions.create and audio.speech.create (OpenAI, compat incl. Groq, native Together). Transcriptions price from usage token buckets or whole-second durations on a JSON response_format — a non-JSON format is recorded unpriced, never guessed; speech prices from the input character count measured inside the privacy firewall. audio.translations and usage-less TTS models (gpt-4o-mini-tts) warn once and pass through. See Surface coverage.
  • Video interception — videos.create (OpenAI Sora) and models.generate_videos (Google Veo), priced per second on resolution-gridded cards. Video jobs carry no usage, so billing settles at initiation as a flagged, conservative over-count — while the pre-flight check is exact, denying an over-budget generation before the provider is called. On providers with no video seam, videos.create fails loud instead of passing through untracked.
  • MediaUsage on the wire — non-token billable quantities (image_count, generation_count, video_seconds, audio_seconds, input_characters) plus the resolution / quality selectors, and a modality field on every cost event. Pre-flight budget checks carry estimated_media, the same quantities derived from the request. Unobservable quantities are omitted, routing the call to the unpriced lane — never a fabricated $0. See Privacy.
  • UnsupportedSurfaceError — raised when a wrapped client's adapter serves no seam for a requested media surface, instead of letting a spend surface run untracked. A deep import (from solwyn.exceptions import UnsupportedSurfaceError) until 0.3.0, which also exported it from the package root. See Exceptions.

No new configuration options. Pre-media wire payloads are byte-identical; the new fields are omitted from the wire for text calls.

0.1.12 — 2026-07-10

Added

  • First-class Together AI provider — wrap a native Together or AsyncTogether client directly; detection is duck-typed by module and class, and Together-hosted OpenAI clients (base_url="https://api.together.xyz/v1") are still admitted via the compat profile. Billable surfaces Solwyn does not yet meter on the native client — completions, rerank, code_interpreter, evals — warn once and pass through. The solwyn[together] extra installs together>=2.0 as a convenience; the SDK never imports it. See Together AI.

0.1.11 — 2026-07-09

Added

  • Z.AI compatibility profile — an OpenAI client pointed at api.z.ai (or calling glm-* models) is detected and attributed as provider="zai" for budgets, attribution, and failover. See OpenAI-compatible providers.

Fixed

  • Z.AI streaming usage injection — Z.AI documents stream_options.include_usage, so Solwyn now injects it on streamed calls and reads exact usage from the final chunk instead of falling back to estimation.
  • Type-checking — OpenAI usage values now narrow correctly under mypy.

0.1.10 — 2026-07-06

Added

  • CostPolicy no-op warning — CostPolicy is selectable but inert until the server sends relative price hints; when no candidate carries a hint it degrades to health-based ordering. That fallback now logs a one-time, per-process warning naming the condition — visible, and carrying no request content.

0.1.9 — 2026-07-06

Fixed

  • Privacy: no tracebacks on the budget-denied report path — two logger.warning calls on the budget-denied report-failure path logged full tracebacks (exc_info=True), breaching the firewall convention that only exception class names are ever logged. Both now log the class name only, and a firewall gate asserts the pattern cannot regress. See Privacy.

0.1.8 — 2026-07-02

Fixed

  • Hard deny survives Cloud outages — After an authoritative Cloud hard_deny, if a subsequent live budget check fails because Solwyn Cloud is unreachable, the SDK keeps denying instead of falling through to its outage path — even when fail_open=True. This is sticky enforcement state, not a cache: live Cloud checks still run on every call, and the first Cloud response that allows clears the sticky deny, so recovery is automatic with no client restart. Ordinary pre-deny outages continue to honor fail_open / local enforcement as before. Applies to both sync and async budget enforcement, at the provider-call boundary — a blocked call raises before reaching the underlying LLM SDK.
  • Cloud response mode is authoritative for denials — Denial behavior now keys off the mode in the Cloud budget response rather than the local budget_mode config, fixing local/Cloud mode drift (e.g. local alert_only vs. a Cloud hard_deny, or the reverse). The served decision now matches what Cloud actually decided.

No breaking changes, no wire-contract changes.

0.1.7 — 2026-06-12

Added

  • Amazon Bedrock support (Converse API) — Wrap a boto3 or aioboto3 bedrock-runtime client: Solwyn(boto3.client("bedrock-runtime")). Intercepts converse / converse_stream, which work uniformly across every chat model Bedrock hosts, with exact cache accounting (additive input formula, 5-minute/1-hour cache-write TTL split via usage.cacheDetails), service/latency tier capture, and per-region cost attribution. Bedrock participates in cross-provider failover in both directions. Zero new runtime dependencies — boto3 is never imported (detection is duck-typed); the solwyn[bedrock] extra installs boto3>=1.34 as a convenience. invoke_model / invoke_model_with_response_stream raise ConfigurationError instead of silently bypassing budget tracking. See Amazon Bedrock.
  • OpenAI-compatible providers — Point an openai.OpenAI client at xAI, DeepSeek, Mistral, Qwen, Groq, Together, Fireworks, Perplexity, Azure OpenAI, OpenRouter, Ollama, vLLM, LM Studio, or any compatible endpoint via base_url; Solwyn detects the real provider for attribution, budgets, and failover instead of mislabeling it openai. Streaming usage (stream_options.include_usage) is requested only where documented-safe per provider. See OpenAI-compatible providers.
  • provider= constructor argument — Explicit provider identity for the primary client when auto-detection cannot name the endpoint (e.g. provider="vllm" on a non-default port). Fallback specs accept a matching 4th element: (client, model, default_params, provider). An override relabels within the same API dialect only; unknown or dialect-mismatched values raise ConfigurationError at construction.
  • Flagged estimated usage — When a provider returns no usage data, the SDK reports length-based estimates explicitly marked token_details.is_estimated=true (serialized only when true) and logs a one-time WARNING. Budgets still enforce; degraded accounting is loud, never silently zero.
  • Same-dialect failover passthrough — Hops between OpenAI-dialect providers (e.g. Groq → OpenRouter) are native passthrough: tools, JSON mode, and streaming survive. On cross-provider hops, endpoint-scoped extra_headers / extra_query / extra_body are stripped and max_completion_tokens ⇄ max_tokens is rewritten per target. See Provider Failover.
  • Per-event ingest rejection logging — Solwyn Cloud now accepts well-formed metadata batches with a 202 and reports per-event rejections in the response body instead of failing whole batches. The SDK surfaces these as one aggregated WARNING per distinct (code, model) per batch on the solwyn.reporter logger (reporter.ingest_events_rejected), with the server's guidance message logged verbatim. Rejected events are terminal (never re-queued); accepted events in the same batch remain recorded. Malformed response bodies fail open to the previous count-only acknowledgment, escalating to ERROR after 10 consecutive occurrences. See Logging.
  • New wire fields — Fifteen new provider values (bedrock plus fourteen OpenAI-compatible identifiers), optional provider_region (omitted when unset), service_tier on budget confirms, token_details.is_estimated, and model identifiers up to 2048 characters (Bedrock ARNs).

0.1.6 — 2026-06-06

Added

  • True cross-provider failover — Configure a failover chain with fallback=[(client, model), (client, model, default_params)] spanning OpenAI, Anthropic, and Google. When a provider fails or its circuit is open, Solwyn translates the request and retries it on the next provider in-process. See Provider Failover.
  • Selection policies — selection_policy= accepts HealthBasedPolicy (default) or LatencyPolicy to control the order in which healthy candidates are attempted.
  • Request translation — Cross-provider hops translate the request shape through a canonical subset (structural only — never content). Untranslatable shapes fail loud before any network call.
  • New constructor arguments — model= (primary entry model), fallback=, default_params= (global fill-absent params), and selection_policy=.
  • Failover tuning — failover_total_timeout, failover_idempotency ("safe" / "never" / "always"), same_provider_retries, and circuit_breaker_recovery_timeout_jitter. Per-call override with the solwyn_idempotent keyword.
  • New exceptions — UntranslatableRequestError and UntranslatableModelError, both carrying structural labels only.
  • New metadata fields — is_provider_fallback, requested_provider, requested_model, failover_reason, failover_error_class, attempt_index, possibly_succeeded, and call_id on the reported event.

Changed (BREAKING)

  • fallback_model and primary_provider removed. Same-provider model fallback is now expressed as a same-provider entry in the fallback= chain (e.g. fallback=[(OpenAI(), "gpt-4o-mini")]); the primary provider is always auto-detected from the wrapped client. The SOLWYN_FALLBACK_MODEL and SOLWYN_PRIMARY_PROVIDER environment variables are no longer read. Migration: replace fallback_model="x" with fallback=[(SameClient(), "x")], and delete any primary_provider= argument.

0.1.5 — 2026-05-16

Added

  • Agent runs — solwyn.run(name) (sync and async context manager) attributes every LLM call inside the scope to a single agent run, so the dashboard groups cost and latency by run. Calls outside a scope are grouped into a synthetic per-day run. See Agent Runs.
  • solwyn.run_in_executor(...) — Submit threaded work to a ThreadPoolExecutor with the active run tag preserved (contextvars do not propagate into worker threads automatically).
  • solwyn.current_run() — Read the active (agent_run_id, agent_run_name) for correlating your own logs.
  • Wire fields — agent_run_id and agent_run_name added to the reported metadata event.

0.1.4 — 2026-05-13

Added

  • Full token-extraction parity — Complete normalized token details across providers.
  • OpenAI Responses API — Token details extracted from both the Chat Completions and Responses API response shapes.
  • Anthropic cache TTL split — Cache-creation tokens are captured separately as cache_creation_5m_tokens (5-minute TTL, 1.25× rate) and cache_creation_1h_tokens (1-hour TTL, 2× rate), with an aggregate fallback for older responses.
  • OpenAI service tier — The response service_tier is captured and reported on the metadata event when present.

0.1.3 — 2026-05-01

Changed (BREAKING)

  • Single-credential SDK contract. project_id removed from Solwyn() / AsyncSolwyn() constructors and the SOLWYN_PROJECT_ID environment variable is no longer read. The project is resolved server-side from the API key. Migration: delete the project_id= kwarg and unset SOLWYN_PROJECT_ID.
  • Project key format tightened. Project keys now match ^sk_proj_[a-f0-9]{64}$ (was ^sk_solwyn_[a-zA-Z0-9]{32,64}$). Existing keys are not migrated; create a new key from the dashboard.

0.1.2 — 2026-04-17

Added

  • Same-provider model fallback (fallback_model). Retry a failed call once with a different model on the same provider client. (Superseded in 0.1.6 by the fallback= chain.)

0.1.1 — 2026-04-15

Changed

  • Tag-derived versioning — Migrated to hatch-vcs so the package version is derived from the git tag.
  • Expanded test coverage for environment-variable construction and credential validation. No user-facing API changes.

0.1.0 — 2026-04-09

Initial release of the Solwyn Python SDK.

Added

  • Zero-config construction — Solwyn(OpenAI()) and AsyncSolwyn(AsyncOpenAI()) work with no kwargs when SOLWYN_API_KEY is set in the environment.
  • Solwyn and AsyncSolwyn client wrappers — Drop-in wrappers for OpenAI, Anthropic, and Google Gemini clients with budget enforcement, circuit breaking, and metadata reporting.
  • Provider auto-detection — Automatically detects the LLM provider from the client instance. No provider= argument needed.
  • Normalized token extraction — Extracts and normalizes token usage across all three providers into a consistent TokenDetails format.
  • Budget enforcement — Pre-call budget checks via Solwyn Cloud API with local fallback. Supports alert_only (default) and hard_deny modes.
  • Circuit breaker — Process-local circuit breaker with CLOSED/OPEN/HALF_OPEN states for provider health tracking.
  • Metadata reporting — Non-blocking batch reporting of usage events to Solwyn Cloud. Background thread (sync) or asyncio.create_task (async).
  • SolwynConfig — Pydantic-validated configuration with environment variable loading (SOLWYN_* prefix).
  • Exception hierarchy — BudgetExceededError, ProviderUnavailableError, ConfigurationError with structured attributes.
  • OpenAI support — Chat Completions and Responses API response shapes. Optional tiktoken extra for accurate token estimation.
  • Anthropic support — Cache normalization (additive input_tokens). Reasoning tokens documented as always 0.
  • Google Gemini support — Thinking token normalization (candidates + thoughts). usage_metadata handling.
  • Fail-open default — LLM calls proceed when Solwyn Cloud is unreachable. Local tracking until connectivity is restored.
  • Context manager support — with Solwyn(...) and async with AsyncSolwyn(...) for automatic resource cleanup.

On this page