[deanrie]

Checklist

• I have read both the CONTRIBUTING.md and Contributor License Agreement documents.
• I have created an issue or feature request and received approval from xAI maintainers. (consistency fix found by reading the helpers; no issue filed)
• I have tested my changes locally and they pass all CI checks.
• I have added necessary documentation or updated existing documentation. (CHANGELOG)

Description

The listing helpers in files.py and collections.py convert the order, sort_by, and metric_space literals to protobuf enums with a match whose case _ returns a default (or the UNKNOWN enum value):

def _order_to_pb(order: Order | None) -> files_pb2.Ordering:
    match order:
        case "asc": ...
        case "desc": ...
        case _: return files_pb2.Ordering.ASCENDING

So at runtime client.files.list(order="dsc") lists ascending, sort_by="created" sorts by the default column, and collections.create(metric_space="cos") creates a collection with HNSW_METRIC_UNKNOWN, all without a word. Type checkers catch these for literal arguments, but values that come from config, CLI flags, or user input reach the SDK as plain str.

Every other literal parameter in the SDK already raises: reasoning_effort (chat.py), service_tier, search mode, image format / quality / aspect_ratio / resolution, field definition op. This change brings the five sort/order/metric helpers in line: an unknown non-None value raises ValueError naming the accepted values; None keeps its current meaning (the default, or ORDERING_UNKNOWN for collections, which lets the server choose).

Tests

• tests/sync/files_test.py: "dsc" and "created" raise with the expected messages; existing None assertions unchanged.
• tests/sync/collections_test.py: "dsc", "names", "created", "cos" raise; None still maps to the previous defaults.

Both new tests fail on main. uv run pytest on the four files/collections test modules: 251 passed. ruff check, ruff format --check, pyright clean on the touched files.