Skip to content

v0.13.0 - Adapter capability contracts and opt-in resilience

Choose a tag to compare

@EduDanielV EduDanielV released this 17 Aug 04:18
· 3 commits to main since this release

Provider-neutral adapter contracts, honest capability selection, passive
health, structured failures, opt-in resilience, and an expanded voice
roster. Every adapter still ships present and importable, never
framework-selected: an application always names the one it wants.

✨ Added

  • Immutable adapter contracts in sett/core_ruler/adapter.py:
    AdapterCapabilities, AdapterRequirements, AdapterHealth,
    AdapterErrorView, AdapterHandle, AdapterSelection. Every
    capability field is tri-state (yes / no / never declared), never a
    plain boolean, and views are detached, JSON-safe copies.
  • select_adapter(): pure filtering with a stable, explained rejection
    reason per excluded candidate, passive health/circuit-state checks, and
    caller-owned tie-breaking through SelectionPolicy /
    PrioritySelectionPolicy. SETT ships no provider default or
    recommendation - selection policy belongs to the application.
  • SETTAdapterError as the structured common parent of the existing
    SETTLLMAdapterError and SETTServiceAdapterError. Official adapters
    now normalize authentication, quota, timeout, unavailable,
    invalid-response, unsupported-capability and configuration failures,
    always preserving the original provider exception as __cause__.
  • CircuitBreaker, CircuitBreakerPolicy, CircuitState and
    execute_with_resilience() in the new sett.core_ruler.resilience.
    Retry and circuit breaking are both off by default; retry additionally
    refuses to run without an explicit idempotency statement.
  • Sanitized adapter trace events: call, health, retry, circuit and
    fallback-selection. Prompts, audio, responses, credentials and raw
    provider messages never appear in them.
  • Remote voice adapters: Deepgram STT, Azure Speech TTS/STT, AssemblyAI
    STT, Gladia STT, OpenAI-hosted Whisper STT, Cartesia TTS.
  • Local voice adapters: pyttsx3 TTS, faster-whisper STT, Kokoro TTS,
    Piper TTS. Model loading is deferred until first use where applicable,
    so importing the module never pays a load cost the application doesn't
    ask for.
  • EdgeTTSAdapter, explicitly labeled community/unofficial in its own
    docstring: it calls Microsoft Edge's reader-mode API rather than the
    supported Azure Speech API, and callers should read that distinction
    before using it commercially.
  • sett.testing.adapter_contract: a dependency-free contract kit any
    third-party adapter author can run without copying SETT's own test
    suite, covering capability immutability, lifecycle honoring,
    cancellation-before-contact, error normalization, __cause__
    preservation, secret-free views, and honest UNKNOWN health.
  • docs/adapters.md and examples/adapter_selection.py.

🐛 Fixed

  • The internal execution-context conformance helper _is_uuid() raised
    NameError when called directly instead of importing UUID first.

🔄 Changed

  • LLMBase, TTSBase, STTBase and SentimentBase now provide
    concrete capabilities, health and non-billable check_health()
    members. Existing v0.12 third-party subclasses need no changes to gain
    them.
  • All eight existing official adapters declare only the behavior their
    current synchronous implementation actually has, and feed the same
    passive health/tracing machinery as the new ones.
  • Retry moved from sett.core_ruler.retry to sett.core_ruler.resilience,
    alongside the new circuit breaker so both share one failure
    classification. The old module path remains as a compatibility
    re-export.
  • CircuitBreaker is now covered by the documented concurrency
    guarantees and an 8-thread, 2,000-failure stress test. A late failure
    from a call already in flight no longer moves an OPEN circuit's
    timestamp or postpones recovery; a failed HALF_OPEN probe still
    starts a new recovery timeout.
  • The living adapter and execution-context design documents moved to
    stable canonical paths (docs/adapter_contract.md,
    docs/execution_context.md) instead of versioned filenames, so future
    revisions update in place instead of creating parallel contracts.
  • Prose across the project now favors commas, semicolons, colons,
    parentheses or a sentence break over a dash-shaped pause. Arithmetic
    operators, list markers, changelog dates, ranges and tool directives
    keep their functional symbols unchanged.
  • OpenAI, Anthropic and Gemini client construction now preserves
    SETT-owned adapter, cancellation and timeout exceptions unchanged,
    matching their real call paths, while genuine provider construction
    failures still arrive normalized.

✅ Compatibility

  • Zero breaking changes in this release.
  • Every existing third-party adapter written against v0.12's LLMBase /
    TTSBase / STTBase / SentimentBase keeps instantiating unmodified.
  • The 893 tests of v0.12.0 pass unmodified.
  • Reference-consumer compatibility: the private companion-assistant
    application's suite (1,175 tests) passes against this source release
    with no application code changes beyond its own declared sett-framework
    version pin. The only local failures came from an audio-hardware gap in
    the verification environment, unrelated to this release.

💖 Sponsors

  • Sponsors: eight tiers from a symbolic $1 up to logo
    placement on 4humanityAI.com, with an explicit note on what sponsorship
    does and does not buy.

Known limitations

  • No Capability Broker, credential/secret store, or billing/quota
    handling ships in SETT. Provider selection by cost, plan or commercial
    preference is deliberately left to the consuming application.
  • Health and circuit-breaker state live in process memory only; neither
    persists across a restart.
  • EdgeTTSAdapter depends on an interface Microsoft documents for its
    reader feature, not a supported API contract - stable in practice for
    years, but outside the same guarantee the other adapters carry, and
    flagged as such in its own docstring.
  • Declaring a capability as supported describes what an adapter's
    current implementation does, not what a specific provider account,
    plan or region will actually grant at call time.
  • The public namespace of the submodules (names without a leading
    underscore that live outside sett.__all__) still has no formal
    policy; that decision remains deferred to the v1.0 freeze.

Status

  • 995 tests passing (893 immediately before this release).
  • Reference-consumer compatibility: the private companion-assistant
    application's full suite (1,175 tests) passes against this source
    release with zero application code changes beyond its own version pin.
  • Zero mandatory dependencies in the core framework. Every provider
    integration, old and new (OpenAI, Anthropic, Gemini, Ollama, Google
    Cloud, ElevenLabs, Deepgram, Azure Speech, AssemblyAI, Gladia, Cartesia,
    pyttsx3, faster-whisper, Kokoro, Piper, edge-tts), is an optional extra.

See CHANGELOG.md for the complete, itemized history of this and every prior version.