From d45e81cbd34d917487cf894fa1c0ba61d49b5c6c Mon Sep 17 00:00:00 2001
From: Sean Brar <hello@seanbrar.com>
Date: Wed, 4 Mar 2026 22:01:09 -0800
Subject: [PATCH] refactor(api): use Sequence for read-only collection
 parameters
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace concrete `list[...] | tuple[...]` unions with
`collections.abc.Sequence` in the public API signatures for `run_many`,
`create_cache`, `normalize_request`, and `create_cache_impl`.

These functions only iterate over their inputs (never mutate), so
`Sequence` accurately reflects the contract.  Because `Sequence` is
covariant, this eliminates mypy invariance errors when callers pass a
`list[str]` where `list[str | None]` was expected — a paper cut that
previously required callers to use tuples or widen their annotations.

All imports are typing-only (behind `TYPE_CHECKING`).  No runtime
behavior change.
---
 src/pollux/__init__.py | 8 +++++---
 src/pollux/cache.py    | 4 +++-
 src/pollux/request.py  | 6 ++++--
 3 files changed, 12 insertions(+), 6 deletions(-)

diff --git a/src/pollux/__init__.py b/src/pollux/__init__.py
index e07db9e..ee7d517 100644
--- a/src/pollux/__init__.py
+++ b/src/pollux/__init__.py
@@ -35,6 +35,8 @@
 from pollux.source import Source
 
 if TYPE_CHECKING:
+    from collections.abc import Sequence
+
     from pollux.providers.base import Provider
 
 try:
@@ -79,9 +81,9 @@ async def run(
 
 
 async def run_many(
-    prompts: str | list[str | None] | tuple[str | None, ...] | None = None,
+    prompts: str | Sequence[str | None] | None = None,
     *,
-    sources: tuple[Source, ...] | list[Source] = (),
+    sources: Sequence[Source] = (),
     config: Config,
     options: Options | None = None,
 ) -> ResultEnvelope:
@@ -160,7 +162,7 @@ async def continue_tool(
 
 
 async def create_cache(
-    sources: tuple[Source, ...] | list[Source],
+    sources: Sequence[Source],
     *,
     config: Config,
     system_instruction: str | None = None,
diff --git a/src/pollux/cache.py b/src/pollux/cache.py
index fe06eed..63bf47a 100644
--- a/src/pollux/cache.py
+++ b/src/pollux/cache.py
@@ -15,6 +15,8 @@
 from pollux.retry import RetryPolicy, retry_async, should_retry_side_effect
 
 if TYPE_CHECKING:
+    from collections.abc import Sequence
+
     from pollux.config import Config
     from pollux.providers.base import Provider
     from pollux.source import Source
@@ -209,7 +211,7 @@ async def _upload(_fp: str = fp, _mt: str = mt) -> Any:
 
 
 async def create_cache_impl(
-    sources: tuple[Source, ...] | list[Source],
+    sources: Sequence[Source],
     *,
     provider: Provider,
     config: Config,
diff --git a/src/pollux/request.py b/src/pollux/request.py
index dac30c4..baf8872 100644
--- a/src/pollux/request.py
+++ b/src/pollux/request.py
@@ -10,6 +10,8 @@
 from pollux.source import Source
 
 if TYPE_CHECKING:
+    from collections.abc import Sequence
+
     from pollux.config import Config
 
 
@@ -24,8 +26,8 @@ class Request:
 
 
 def normalize_request(
-    prompts: tuple[str | None, ...] | list[str | None] | str | None,
-    sources: tuple[Source, ...] | list[Source],
+    prompts: str | Sequence[str | None] | None,
+    sources: Sequence[Source],
     config: Config,
     *,
     options: Options | None = None,