feat: support V1 native fast search mode

The V1 Search API added a native `fast` mode — high quality search
within a one-second latency budget, sitting between turbo and basic —
shipped in parallel-web 1.3.0. The CLI still treated `fast` as a
Beta-only alias: it downgraded to `basic` and printed a deprecation
warning, so the new mode was unreachable.

`--mode fast` now passes through as a first-class V1 value with no
warning. The remaining Beta-only names (`one-shot`, `agentic`) keep
their translation and deprecation notice. Mode choices are reordered to
list V1-native values before the legacy aliases, and the parallel-web
floor moves to 1.3.0, whose search() typing includes "fast".

Verified against the live API: `--mode fast` returns results with a
clean stderr.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: zhengchaol

parallel_web_tools/cli/commands.py

@@ -1088,18 +1088,19 @@ def memory_clear(memory_scope_key: str | None, confirm_clear: bool, output_json:
 # Search Command
 # =============================================================================
 
-# Beta -> V1 mode mapping. Beta had three modes; V1 has three (turbo/basic/
-# advanced). We keep the old values as accepted CLI inputs and translate them so
-# existing scripts work.
+# Search mode translation. V1 accepts turbo/fast/basic/advanced natively; the
+# Beta-only values stay accepted CLI inputs and are translated so existing
+# scripts keep working. Beta's `fast` used to downgrade to basic, but V1 now has
+# a native fast mode of its own, so the name passes through.
 _SEARCH_MODE_MAP = {
-    "fast": "basic",
-    "one-shot": "basic",
-    "agentic": "advanced",
     "turbo": "turbo",
+    "fast": "fast",
     "basic": "basic",
     "advanced": "advanced",
+    "one-shot": "basic",
+    "agentic": "advanced",
 }
-_DEPRECATED_SEARCH_MODES = {"fast", "one-shot", "agentic"}
+_DEPRECATED_SEARCH_MODES = {"one-shot", "agentic"}
 
 
 def _emit_deprecation(message: str) -> None:
@@ -1166,7 +1167,8 @@ def build_search_v1_kwargs(
     "--mode",
     type=click.Choice(list(_SEARCH_MODE_MAP.keys())),
     default="basic",
-    help="Search mode: turbo (fastest), basic, or advanced (one-shot/fast → basic, agentic → advanced)",
+    help="Search mode: turbo (fastest), fast (high quality within ~1s), basic, "
+    "or advanced (highest quality; one-shot → basic, agentic → advanced)",
     show_default=True,
 )
 @click.option("--max-results", type=int, help="Maximum results (defaults to server-side default of 10)")

pyproject.toml

@@ -29,7 +29,7 @@ classifiers = [
 ]
 
 dependencies = [
-    "parallel-web>=1.2.0,<2",
+    "parallel-web>=1.3.0,<2",
     "python-dotenv>=1.0.0",
     # CLI dependencies (minimal - search, extract, enrich with CLI args)
     "click>=8.1.0",

tests/test_cli.py

@@ -1201,20 +1201,6 @@ def test_explicit_queries_override_objective_fallback(self):
         assert kwargs["search_queries"] == ["first query", "second query"]
         assert kwargs["objective"] == "overarching goal"
 
-    def test_mode_fast_maps_to_basic(self):
-        """Should map old `fast` mode to V1 `basic`."""
-        kwargs = build_search_v1_kwargs(
-            objective=None,
-            query=("q",),
-            mode="fast",
-            max_results=None,
-            source_policy=None,
-            excerpt_max_chars_per_result=None,
-            excerpt_max_chars_total=None,
-            fetch_policy=None,
-        )
-        assert kwargs["mode"] == "basic"
-
     def test_mode_one_shot_maps_to_basic(self):
         """Should map old `one-shot` mode to V1 `basic`."""
         kwargs = build_search_v1_kwargs(
@@ -1244,8 +1230,8 @@ def test_mode_agentic_maps_to_advanced(self):
         assert kwargs["mode"] == "advanced"
 
     def test_new_mode_values_pass_through(self):
-        """Should accept V1-native `turbo`/`basic`/`advanced` values directly."""
-        for new_mode in ("turbo", "basic", "advanced"):
+        """Should accept V1-native `turbo`/`fast`/`basic`/`advanced` values directly."""
+        for new_mode in ("turbo", "fast", "basic", "advanced"):
             kwargs = build_search_v1_kwargs(
                 objective=None,
                 query=("q",),
@@ -1621,7 +1607,6 @@ def _setup_mock_search(self, mock_client):
     @pytest.mark.parametrize(
         "deprecated_mode,expected_new",
         [
-            ("fast", "basic"),
             ("one-shot", "basic"),
             ("agentic", "advanced"),
         ],
@@ -1644,7 +1629,7 @@ def test_deprecated_modes_emit_warning_to_stderr(self, runner, mock_cli_client,
         call_kwargs = mock_cli_client.search.call_args.kwargs
         assert call_kwargs["mode"] == expected_new
 
-    @pytest.mark.parametrize("new_mode", ["basic", "advanced"])
+    @pytest.mark.parametrize("new_mode", ["turbo", "fast", "basic", "advanced"])
     def test_new_modes_do_not_emit_warning(self, runner, mock_cli_client, new_mode):
         """Should not warn when V1-native mode values are used."""
         self._setup_mock_search(mock_cli_client)