Deprecate standalone package: Pipecat Flows is now part of Pipecat

[kompfner]

Companion to pipecat-ai/pipecat#4882, which folds Pipecat Flows into core pipecat-ai under the pipecat.flows namespace.

This PR turns pipecat-ai-flows into its final, frozen snapshot before the repo is archived:

• Deprecation warning — importing pipecat_flows now emits a DeprecationWarning pointing at pipecat.flows. The code is otherwise unchanged and still works.
• Dependency pin — pipecat-ai>=1.4.0,<1.5.0, the last Pipecat line without built-in Flows. This package stays the Flows provider for that era and deliberately cannot coexist with a pipecat-ai that already bundles pipecat.flows — so upgrading Pipecat past 1.4.x forces dropping this package and importing pipecat.flows. That's the migration pressure, done cleanly, and it resolves/tests against current Pipecat today.
• README — replaced with a short redirect: before/after import, where things moved, and a pointer to the archived changelog. The standalone release history stays in CHANGELOG.md.

Why a clean break, not a pipecat_flows → pipecat.flows shim

An alternative was to make this package a thin re-export shim — pipecat_flows simply does from pipecat.flows import * and forwards to the in-core framework, so existing from pipecat_flows import ... code keeps working transparently. We deliberately didn't, for a few reasons:

• A shim can't be "frozen." By construction it forwards to whatever pipecat.flows is installed, so it would keep delivering new Flows behavior indefinitely — the opposite of a final, frozen release. Stopping that would mean pinning pipecat-ai to an exact version, which is brittle.
• A shim would require the thing it supersedes. Forwarding to pipecat.flows means depending on pipecat-ai>=1.5.0 — i.e. installing the standalone package and the built-in one side by side, exactly the redundant dual-install we're steering people away from.
• The frozen snapshot is mutually exclusive with built-in Flows. Pinning <1.5.0 (the pre-Flows line) means this package and a pipecat.flows-bearing Pipecat can't be installed together, so upgrading Pipecat forces a clean migration to pipecat.flows rather than letting pipecat_flows imports live on forever with no nudge.
• It avoids an open-ended compatibility commitment. A perpetual forwarding layer is something core Pipecat would implicitly have to keep working across future versions; a frozen final release tied to the 1.4.x era has a clear, bounded end.

For the one case a shim wouldn't have helped with anyway — an older pipecat-ai-flows (which allowed pipecat-ai<2) installed next to a Pipecat that already has Flows — core Pipecat now logs an error on import pipecat.flows telling the user to uninstall the standalone package (see pipecat#4882).

Sequencing

Not blocked on the 1.5.0 release (it pins to 1.4.x, which exists today), but the migration target it points users at — pipecat.flows — only exists once pipecat#4882 lands and pipecat-ai 1.5.0 ships. So:

• Release this as the final pipecat-ai-flows around/after 1.5.0 is out, so from pipecat.flows import ... actually works for anyone following the warning.
• After the final release, archive this repository.
• If pipecat.flows first ships in a version other than 1.5.0, set the cap to < <that version> (the first Pipecat with built-in Flows) and update the README's "as of pipecat-ai 1.5.0" reference to match.

🤖 Generated with Claude Code

[markbackman]

Looks great!

Just double check links are correct before merging this PR (post Pipecat release). Thanks for migrating!

(I didn't mean to approve yet. We can do that after the Pipecat release with a final validation.)

[markbackman]

LGTM! I'm having Claude take a look, just in case.

Update: Claude agrees. No findings.

[kompfner]

post Pipecat release

Agreed, we should hold off on merging this until post-Pipecat release to avoid the Pipecat Flows GitHub README awkwardly pointing people to use Flows embedded in base Pipecat, when a version of Pipecat with Flows in it hasn't been published yet.

[filipi87]

It's all in Pipecat now. Beautiful. 🙂