docs: document Pipecat + LiveKit voice adapters and TS-parity position#54
Merged
Conversation
The README led with generic LLM adapters and never surfaced the two voice adapters that ship in the Python package (Pipecat, LiveKit), so a voice-AI builder (STT->LLM->TTS) couldn't tell floe-guard covers their stack. - Add ### Pipecat (voice) and ### LiveKit (voice) sections with runnable Python examples using the real import paths (floe_guard.integrations.pipecat.FloeBudgetGuardProcessor and floe_guard.integrations.livekit.LiveKitBudgetGuard). - Surface both in the top-line "Works with" list. - Add a compact adapter x language matrix making the Python-only reality of the voice adapters explicit. - Add an explicit TypeScript voice-parity paragraph: no TS voice adapter today, JS path is Vercel AI middleware (text), voice builders use the Floe proxy or the Python adapters; not yet available, no committed roadmap. - Cross-link the Floe docs "Add Floe to your existing pipeline" guide. Docs-only. No code touched.
📝 WalkthroughWalkthroughThe README expands its compatibility overview and adds voice adapter documentation covering per-turn budgeting, pricing, Python integrations, adapter coverage, and TypeScript alternatives. ChangesREADME documentation updates
Estimated code review effort: 1 (Trivial) | ~4 minutes Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the top-level README to explicitly document the existing Python voice adapters (Pipecat and LiveKit) and to clarify current Python vs TypeScript adapter coverage, including the lack of a TypeScript voice adapter today.
Changes:
- Adds a new “Voice adapters (STT → LLM → TTS)” section with runnable Pipecat and LiveKit examples using the public integration APIs.
- Surfaces Pipecat/LiveKit in the top “Works with” line and adds an adapter × language matrix.
- Adds a TypeScript voice-parity note (JS package is Vercel AI SDK middleware only; voice metering on Node is manual today) and links to the “Add Floe to your existing pipeline” guide.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@README.md`:
- Around line 580-601: The README examples are presented as runnable but contain
undefined placeholders. In README.md lines 580-601, either add concrete Pipecat
transport, STT, LLM, TTS, and context setup or clearly label the block as a
fragment; in README.md lines 621-634, define agent and ctx and wrap the calls in
an async entry point, or clearly label that block as a fragment.
- Around line 663-671: Update the TypeScript voice-adapter status section around
“There is no TypeScript voice adapter today” to remove time-sensitive claims
about “today” and the absence of a committed roadmap, either linking a dated
canonical issue/discussion or stating only that no TypeScript voice adapter
ships in the current release.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
Address CodeRabbit on PR #54: - Pipecat and LiveKit code blocks are integration-point fragments (transport, stt, llm, tts, session, agent, ctx are the reader's existing objects). Label both as fragments and point Pipecat at the runnable examples/voice_turn_budget.py (no API key, no network). A full inline voice agent needs a real transport + room creds — that belongs in examples/, not the README. - Drop the aging 'today' / 'no committed roadmap' phrasing; state only that no TypeScript voice adapter ships in this release.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@README.md`:
- Around line 667-675: Update the README paragraph describing the Python
Pipecat/LiveKit adapters so its “whole turn” enforcement claim is conditional on
STT/TTS pricing being configured. Clarify that LLM enforcement always applies,
while STT/TTS metering is optional and depends on configured per-unit prices or
record_tool usage.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
Comment on lines
+667
to
+675
| **This release ships no TypeScript voice adapter.** The JS package | ||
| ([`js/`](js/)) ships one surface — the Vercel AI SDK middleware — and it is | ||
| **text-only**: it guards a wrapped `LanguageModel`, not a running STT → LLM → TTS | ||
| session. A voice/telephony builder on a Node stack should either drive the LLM | ||
| turn through the Vercel AI middleware and meter STT/TTS spend by hand via | ||
| `recordTool`, or run the LLM leg through the **hosted [Floe proxy](#upgrade-to-hosted-floe)** | ||
| (un-bypassable, cross-vendor) — or use the Python Pipecat / LiveKit adapters | ||
| above, which enforce the whole turn. No native TypeScript Pipecat/LiveKit voice | ||
| adapter ships in this release. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Qualify the “whole turn” enforcement claim.
Lines 566 and 641-643 state that STT/TTS spend is metered only when per-unit prices are supplied, so “which enforce the whole turn” is too broad. Clarify that the Python adapters enforce the complete turn when STT/TTS pricing is configured, or otherwise describe LLM enforcement plus optional STT/TTS metering via record_tool.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.md` around lines 667 - 675, Update the README paragraph describing the
Python Pipecat/LiveKit adapters so its “whole turn” enforcement claim is
conditional on STT/TTS pricing being configured. Clarify that LLM enforcement
always applies, while STT/TTS metering is optional and depends on configured
per-unit prices or record_tool usage.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The gap
The README led with generic LLM adapters (OpenAI, Anthropic, LangChain, …) and never surfaced the two voice adapters that already ship in the Python package. A voice-AI builder running an STT → LLM → TTS pipeline couldn't tell from the README that floe-guard covers their stack — the Pipecat and LiveKit adapters were undocumented despite being shipped code with an optional extra each.
The fix (docs-only, no code touched)
### Pipecat (voice)and### LiveKit (voice)sections with short runnable Python examples using the real import paths and public API found in source.Verified in source
src/floe_guard/integrations/pipecat.py—FloeBudgetGuardProcessor(FrameProcessor placed after the LLM service; reserves onLLMFullResponseStartFrame, settles fromLLMUsageMetricsData; requiresenable_metrics=True, enable_usage_metrics=True). Extra:floe-guard[pipecat](pyproject.toml).src/floe_guard/integrations/livekit.py—LiveKitBudgetGuard.attach(session, agent)(reserves inllm_node, settles onmetrics_collectedLLMMetrics; optionalstt_usd_per_second/tts_usd_per_1k_chars). Extra:floe-guard[livekit](pyproject.toml).examples/voice_turn_budget.py— runnable Pipecat voice demo (referenced from the new section).pyproject.toml—pipecat = ["pipecat-ai>=1.0"],livekit = ["livekit-agents>=1.0"].js/src/) — no pipecat/livekit/voice references anywhere; onlymiddleware.ts(Vercel AI SDK, text). Confirms the Python-only / no-TS-parity claim.All examples use import paths and APIs confirmed in the source above; nothing was invented.
Summary by CodeRabbit