upsert_records(ns, records) fails with a bare TypeError — should teach the keyword-only call shape #691

Repro

index.upsert_records("my-namespace", records)
# TypeError: Index.upsert_records() takes 1 positional argument but 3 were given

Why this matters

The keyword-only signature is correct — the parameter order here (records, then namespace) differs from earlier SDK generations' upsert_records(namespace, records), so accepting positionals would silently mis-bind old-style calls. Keyword-only is the right guard.

But the failure is a bare interpreter TypeError that names neither the parameters nor the fix. Callers arriving with the old muscle memory (or an LLM's training-data priors — see below) get no path forward from the error itself.

Proposed fix

Keep the signature keyword-only; intercept positional misuse and raise PineconeTypeError (already a TypeError subclass, so existing except TypeError handlers keep working) with the exact call shape:

upsert_records() accepts keyword arguments only: upsert_records(namespace="...", records=[...]).
Positional arguments are rejected because the parameter order changed across SDK generations.

A small functools.wraps guard preserves inspect.signature() (via __wrapped__), so IDEs and introspection still see the real keyword-only signature. Applies to the sync, async, and gRPC variants; the same pattern can be extended to other keyword-only methods later if it proves useful.

How we found it

Cold-agent audit for an upcoming blog post: 2 of 2 SDK-path agents guessed the positional form, burned 3–4 turns on the bare TypeError, and one resorted to grepping the installed SDK source to find the contract. The error message could have cost them zero.