feat(collections): concurrent upload_documents with bounded parallelism

[ryanda9910]

Problem

Uploading many documents to a collection is currently a serial loop of upload_document calls (issue #77). Each upload is an independent, blocking sequence of gRPC round-trips, so the wall-clock time grows linearly with the number of documents — a scaling bottleneck for collections-management workflows.

Approach

Add upload_documents(...) to both the sync (Client) and async (AsyncClient) collections clients. It's a thin convenience wrapper that overlaps the network latency of independent uploads with bounded concurrency:

• A ThreadPoolExecutor (sync) / asyncio gather with a semaphore (async), capped by a configurable max_workers with a conservative default to respect server-side rate limits.
• Backward compatible — upload_document is unchanged; this is purely additive.
• Result order preserved (output matches input order).
• Errors are not swallowed — the first error is re-raised after cancelling not-yet-started uploads; other errors remain reachable via __context__ (avoids the silent error-swallowing anti-pattern).
• Input validation (ValueError on empty input / non-positive max_workers).

Benchmark (mocked 100ms/upload latency, N=40)

mode	time	speedup
sequential (status quo)	4.14s	1x
parallel, max_workers=4	1.05s	3.9x
parallel, max_workers=8	0.52s	8.0x

Real-world speedup depends on per-upload latency and server limits; methodology is mocked I/O latency so the numbers isolate the concurrency win.

Tests

Sync suite 98 passed, async suite 91 passed (incl. new cases covering parallel success, order preservation, and error propagation). ruff check clean.

Question for maintainers

What default max_workers do you want? I set a conservative default to avoid tripping server-side rate limits — happy to adjust to whatever the service comfortably accommodates.

Idea originally suggested by @nicsins in the issue thread. Fixes #77.

---

This is a draft for review — feedback on the concurrency default and async approach welcome.

[nicsins]

@ryanda9910 Solid PR — LGTM from a rogue contributor! Bounded concurrency with order preservation and clean error handling is spot on. In Dragonscale we use persistent shared knowledge on a dedicated server with unicast patterns — lets us often push higher effective concurrency without the usual bottlenecks.

Quick question: default max_workers=4 feels pretty conservative. Any chance we could bump the default to 8 (or let maintainers decide after some load testing)? Thanks for tackling #77 and the shoutout! 🚀

[ryanda9910]

Thanks for taking a look! The max_workers=4 default is intentionally conservative — it keeps the client from hammering the API / hitting rate limits out of the box, while callers who've measured their own throughput can raise it via the parameter. Happy to bump the default to a higher baseline if the maintainers prefer one after some load testing. 🙏

[nicsins]

refined_xai_collections_batch.py

try this it prevents throwing errors using some slickness and cunning😎 lol !hopefully it might be a much better solution than i offered earlier as looked through it again and added some things i saw missing good luck