release: 0.5.0 — instance-based API refactor

[nicolotognoni]

Summary

Patter 0.5.0 ships a clean, instance-based public API for both the Python and TypeScript SDKs. Every provider — carrier, engine, STT, TTS, tunnel — is a typed class that reads its credentials from environment variables by default, so a genuine 4-line quickstart composes out of the box:

from patter import Patter, Twilio, OpenAIRealtime
phone = Patter(carrier=Twilio(), phone_number="+15550001234")
agent = phone.agent(engine=OpenAIRealtime(), system_prompt="You are helpful.")
await phone.serve(agent, tunnel=True)

TypeScript mirror:

import { Patter, Twilio, OpenAIRealtime } from "getpatter";
const phone = new Patter({ carrier: new Twilio(), phoneNumber: "+15550001234" });
const agent = phone.agent({ engine: new OpenAIRealtime(), systemPrompt: "You are helpful." });
await phone.serve({ agent, tunnel: true });

What's new

• Carriers — patter.carriers.{twilio,telnyx} + flat Twilio / Telnyx
• Engines — patter.engines.{openai,elevenlabs} + flat OpenAIRealtime / ElevenLabsConvAI
• STT — DeepgramSTT, WhisperSTT, CartesiaSTT, SonioxSTT, SpeechmaticsSTT (Python-only), AssemblyAISTT
• TTS — ElevenLabsTTS, OpenAITTS, CartesiaTTS, RimeTTS, LMNTTTS
• Tunnels — CloudflareTunnel(), Static(hostname=...), Ngrok() instances; serve(tunnel=True) kept as dev alias
• Primitives — Tool class + @tool decorator, Guardrail class + guardrail(...) factory
• Env-fallback everywhere — each adapter reads <VENDOR>_API_KEY when the constructor arg is omitted
• TypeScript carrier auto-config — serve() now sets the Twilio voice_url and associates Telnyx numbers automatically (parity with Python)
• Docs — new Setting up Patter nav group with Carrier / Engines / STT / LLM / TTS subsections; fresh engines.mdx pages for both SDKs; every code block paste-runnable

What's removed

• Legacy Patter(twilio_sid=, twilio_token=, openai_key=, deepgram_key=, ...) kwargs
• Legacy string selectors (stt="deepgram", tts="elevenlabs", provider="openai_realtime")
• Factory methods Patter.deepgram(), Patter.whisper(), Patter.elevenlabs(), Patter.openai_tts(), Patter.cartesia(), Patter.rime(), Patter.lmnt(), Patter.guardrail(), Patter.tool()
• Dict-form tool/guardrail definitions (typed instances only)
• ~294 lines of deprecation shim from sdk-py/patter/client.py
• ~251 lines of deprecation shim + sdk-ts/src/provider-resolver.ts from the TypeScript client

Line-count delta

247 files changed, 4,810 insertions, 9,766 deletions → net −4,956 lines.

Test plan

• cd sdk-py && python3 -m pytest — 1327 passed, 8 skipped, 0 failures
• cd sdk-ts && npx tsc --noEmit — clean, exit 0
• cd sdk-ts && npx vitest run — 1013 tests across 60 files, 0 failures
• 4-line Python quickstart runs clean under -W error::DeprecationWarning
• 4-line TypeScript quickstart composes end-to-end via tsx
• Twilio webhook auto-configuration covered by carrier-config.test.ts (TS) and existing Python adapter tests
• Full soak suite (1000-turn cost precision, 20 disconnect/reconnect cycles, 100 concurrent calls RSS growth) all within thresholds

Release process (after merge)

1. Tag v0.5.0 on main → CI publishes to PyPI (OIDC) and npm automatically
2. Create GitHub Release with this PR body

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
patter-06b046ce	🟢 Ready	View Preview	Apr 22, 2026, 4:14 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.