Simplify ServiceSwitcher with closure-based filters

- Make ServiceSwitcherStrategy inherit from BaseObject with properties
  for services and active_service, and move initial service selection
  into the base class
- Add on_service_switched event to ServiceSwitcherStrategy
- handle_frame now returns the switched-to service (or None), allowing
  ServiceSwitcher to swallow ManuallySwitchServiceFrame on switch and
  request metadata from the new active service
- Override push_frame to suppress RequestMetadataFrame and
  ServiceMetadataFrame from inactive services
- Remove ServiceSwitcherFilter and ServiceSwitcherFilterFrame in favor
  of plain FunctionFilter instances with closures that check the
  strategy's active service directly
- FunctionFilter: add FilterType alias
- FunctionFilter: when direction is None, frames in both directions
  are filtered instead of just one
- Add docstrings to ServiceSwitcher and its components

tests/test_filters.py

@@ -14,10 +14,12 @@ from pipecat.frames.frames import (
     UserStartedSpeakingFrame,
     UserStoppedSpeakingFrame,
 )
+from pipecat.pipeline.pipeline import Pipeline
 from pipecat.processors.filters.frame_filter import FrameFilter
 from pipecat.processors.filters.function_filter import FunctionFilter
 from pipecat.processors.filters.identity_filter import IdentityFilter
 from pipecat.processors.filters.wake_check_filter import WakeCheckFilter
+from pipecat.processors.frame_processor import FrameDirection, FrameProcessor
 from pipecat.tests.utils import run_test
 
 
@@ -93,6 +95,98 @@ class TestFunctionFilter(unittest.IsolatedAsyncioTestCase):
             expected_down_frames=expected_down_frames,
         )
 
+    async def test_no_direction_filters_both_directions(self):
+        """When direction is None, frames in both directions are filtered."""
+
+        class UpstreamPusher(FrameProcessor):
+            """Pushes a TextFrame upstream when it receives a system frame."""
+
+            async def process_frame(self, frame: Frame, direction: FrameDirection):
+                await super().process_frame(frame, direction)
+                await self.push_frame(frame, direction)
+                if isinstance(frame, UserStartedSpeakingFrame):
+                    await self.push_frame(TextFrame(text="upstream"), FrameDirection.UPSTREAM)
+
+        async def block_text(frame: Frame):
+            return not isinstance(frame, TextFrame)
+
+        # direction=None: filter applies in both directions. The downstream
+        # TextFrame is blocked and the upstream TextFrame pushed by
+        # UpstreamPusher is also blocked.
+        filter = FunctionFilter(filter=block_text, direction=None)
+        pipeline = Pipeline([filter, UpstreamPusher()])
+        frames_to_send = [
+            TextFrame(text="Hello!"),
+            UserStartedSpeakingFrame(),
+        ]
+        expected_down_frames = [UserStartedSpeakingFrame]
+        expected_up_frames = []
+        await run_test(
+            pipeline,
+            frames_to_send=frames_to_send,
+            expected_down_frames=expected_down_frames,
+            expected_up_frames=expected_up_frames,
+        )
+
+    async def test_downstream_direction_passes_upstream(self):
+        """When direction is DOWNSTREAM, upstream frames pass through unfiltered."""
+
+        class UpstreamPusher(FrameProcessor):
+            """Pushes a TextFrame upstream when it receives a system frame."""
+
+            async def process_frame(self, frame: Frame, direction: FrameDirection):
+                await super().process_frame(frame, direction)
+                await self.push_frame(frame, direction)
+                if isinstance(frame, UserStartedSpeakingFrame):
+                    await self.push_frame(TextFrame(text="upstream"), FrameDirection.UPSTREAM)
+
+        async def block_text(frame: Frame):
+            return not isinstance(frame, TextFrame)
+
+        # direction=DOWNSTREAM: filter only applies downstream, so the
+        # upstream TextFrame pushed by UpstreamPusher passes through.
+        filter = FunctionFilter(filter=block_text)
+        pipeline = Pipeline([filter, UpstreamPusher()])
+        frames_to_send = [UserStartedSpeakingFrame()]
+        expected_down_frames = [UserStartedSpeakingFrame]
+        expected_up_frames = [TextFrame]
+        await run_test(
+            pipeline,
+            frames_to_send=frames_to_send,
+            expected_down_frames=expected_down_frames,
+            expected_up_frames=expected_up_frames,
+        )
+
+    async def test_upstream_direction_passes_downstream(self):
+        """When direction is UPSTREAM, downstream frames pass through unfiltered."""
+
+        class UpstreamPusher(FrameProcessor):
+            """Pushes a TextFrame upstream when it receives a system frame."""
+
+            async def process_frame(self, frame: Frame, direction: FrameDirection):
+                await super().process_frame(frame, direction)
+                await self.push_frame(frame, direction)
+                if isinstance(frame, UserStartedSpeakingFrame):
+                    await self.push_frame(TextFrame(text="upstream"), FrameDirection.UPSTREAM)
+
+        async def block_text(frame: Frame):
+            return not isinstance(frame, TextFrame)
+
+        # direction=UPSTREAM: filter only applies upstream, so the
+        # downstream TextFrame passes through but the upstream TextFrame
+        # pushed by UpstreamPusher is blocked.
+        filter = FunctionFilter(filter=block_text, direction=FrameDirection.UPSTREAM)
+        pipeline = Pipeline([filter, UpstreamPusher()])
+        frames_to_send = [TextFrame(text="Hello!"), UserStartedSpeakingFrame()]
+        expected_down_frames = [UserStartedSpeakingFrame, TextFrame]
+        expected_up_frames = []
+        await run_test(
+            pipeline,
+            frames_to_send=frames_to_send,
+            expected_down_frames=expected_down_frames,
+            expected_up_frames=expected_up_frames,
+        )
+
 
 class TestWakeCheckFilter(unittest.IsolatedAsyncioTestCase):
     async def test_no_wake_word(self):

tests/test_service_switcher.py

@@ -6,6 +6,7 @@
 
 """Unit tests for ServiceSwitcher and related components."""
 
+import asyncio
 import unittest
 from dataclasses import dataclass
 
@@ -122,14 +123,7 @@ class TestServiceSwitcherStrategyManual(unittest.IsolatedAsyncioTestCase):
         self.assertEqual(strategy.services, self.services)
         self.assertEqual(strategy.active_service, self.service1)  # First service should be active
 
-    def test_init_with_empty_services(self):
-        """Test initialization with an empty list of services."""
-        strategy = ServiceSwitcherStrategyManual([])
-
-        self.assertEqual(strategy.services, [])
-        self.assertIsNone(strategy.active_service)
-
-    def test_handle_manually_switch_service_frame(self):
+    async def test_handle_manually_switch_service_frame(self):
         """Test manual service switching with ManuallySwitchServiceFrame."""
         strategy = ServiceSwitcherStrategyManual(self.services)
 
@@ -139,7 +133,7 @@ class TestServiceSwitcherStrategyManual(unittest.IsolatedAsyncioTestCase):
 
         # Switch to service2
         switch_frame = ManuallySwitchServiceFrame(service=self.service2)
-        strategy.handle_frame(switch_frame, FrameDirection.DOWNSTREAM)
+        await strategy.handle_frame(switch_frame, FrameDirection.DOWNSTREAM)
 
         self.assertNotEqual(strategy.active_service, self.service1)
         self.assertEqual(strategy.active_service, self.service2)
@@ -147,21 +141,66 @@ class TestServiceSwitcherStrategyManual(unittest.IsolatedAsyncioTestCase):
 
         # Switch to service3
         switch_frame = ManuallySwitchServiceFrame(service=self.service3)
-        strategy.handle_frame(switch_frame, FrameDirection.DOWNSTREAM)
+        await strategy.handle_frame(switch_frame, FrameDirection.DOWNSTREAM)
 
         self.assertNotEqual(strategy.active_service, self.service1)
         self.assertNotEqual(strategy.active_service, self.service2)
         self.assertEqual(strategy.active_service, self.service3)
 
-    def test_handle_frame_unsupported_frame_type(self):
+    async def test_on_service_switched_event(self):
+        """Test that on_service_switched event fires with correct arguments."""
+        strategy = ServiceSwitcherStrategyManual(self.services)
+
+        switched_events = []
+
+        @strategy.event_handler("on_service_switched")
+        async def on_service_switched(strategy, service):
+            switched_events.append((strategy, service))
+
+        # Switch to service2
+        switch_frame = ManuallySwitchServiceFrame(service=self.service2)
+        await strategy.handle_frame(switch_frame, FrameDirection.DOWNSTREAM)
+        await asyncio.sleep(0)  # Let async event task run
+
+        self.assertEqual(len(switched_events), 1)
+        self.assertIsInstance(switched_events[0][0], ServiceSwitcherStrategyManual)
+        self.assertEqual(switched_events[0][1], self.service2)
+
+        # Switch to service3
+        switch_frame = ManuallySwitchServiceFrame(service=self.service3)
+        await strategy.handle_frame(switch_frame, FrameDirection.DOWNSTREAM)
+        await asyncio.sleep(0)
+
+        self.assertEqual(len(switched_events), 2)
+        self.assertEqual(switched_events[1][1], self.service3)
+
+    async def test_on_service_switched_event_not_fired_for_unknown_service(self):
+        """Test that on_service_switched event does not fire for services not in the list."""
+        strategy = ServiceSwitcherStrategyManual(self.services)
+
+        switched_events = []
+
+        @strategy.event_handler("on_service_switched")
+        async def on_service_switched(strategy, service):
+            switched_events.append(service)
+
+        # Try switching to a service not in the list
+        unknown_service = MockFrameProcessor("unknown")
+        switch_frame = ManuallySwitchServiceFrame(service=unknown_service)
+        await strategy.handle_frame(switch_frame, FrameDirection.DOWNSTREAM)
+        await asyncio.sleep(0)
+
+        self.assertEqual(len(switched_events), 0)
+        self.assertEqual(strategy.active_service, self.service1)  # Unchanged
+
+    async def test_handle_frame_unsupported_frame_type(self):
         """Test that unsupported frame types raise an error."""
         strategy = ServiceSwitcherStrategyManual(self.services)
         unsupported_frame = TextFrame(text="test")  # Not a ServiceSwitcherFrame
 
-        with self.assertRaises(ValueError) as context:
-            strategy.handle_frame(unsupported_frame, FrameDirection.DOWNSTREAM)
+        result = await strategy.handle_frame(unsupported_frame, FrameDirection.DOWNSTREAM)
 
-        self.assertIn("Unsupported frame type", str(context.exception))
+        self.assertIsNone(result)
 
 
 class TestServiceSwitcher(unittest.IsolatedAsyncioTestCase):
@@ -267,7 +306,7 @@ class TestServiceSwitcher(unittest.IsolatedAsyncioTestCase):
                 ManuallySwitchServiceFrame(service=self.service2),
                 TextFrame("Hello 2"),
             ],
-            expected_down_frames=[TextFrame, ManuallySwitchServiceFrame, TextFrame],
+            expected_down_frames=[TextFrame, TextFrame],
             expected_up_frames=[],  # Expect no error frames
         )
 
@@ -333,9 +372,7 @@ class TestServiceSwitcher(unittest.IsolatedAsyncioTestCase):
             ],
             expected_down_frames=[
                 TextFrame,
-                ManuallySwitchServiceFrame,
                 TextFrame,
-                ManuallySwitchServiceFrame,
                 TextFrame,
             ],
             expected_up_frames=[],  # Expect no error frames
@@ -429,9 +466,8 @@ class TestServiceSwitcherMetadata(unittest.IsolatedAsyncioTestCase):
             expected_down_frames=[
                 MockMetadataFrame,  # From startup (service1)
                 TextFrame,
-                ManuallySwitchServiceFrame,
-                TextFrame,
                 MockMetadataFrame,  # From service2 after switch
+                TextFrame,
             ],
             expected_up_frames=[],
         )