docs: document OrderBook.bids/asks sort convention

[Nexory]

The OrderBook model in src/polymarket/models/clob/order_book.py defines bids and asks as tuple[OrderBookLevel, ...] but does not document the sort order returned by the CLOB API.

The convention is non-obvious — _calculate_buy_market_price in src/polymarket/_internal/actions/orders/estimate.py:139 walks reversed(asks) starting from the cheapest level, which implies asks are returned highest-price-first. Similarly bids in _calculate_sell_market_price are reversed to walk from highest, implying bids are returned lowest-price-first.

This is non-obvious for new users and easy to get wrong when writing custom orderbook-walking logic outside the provided estimate_market_price helper.

Suggested change: Add field docstrings on OrderBook.bids and OrderBook.asks noting the sort order:

bids: tuple[OrderBookLevel, ...]
"""Returned by the CLOB API in ascending price order (lowest bid first)."""
asks: tuple[OrderBookLevel, ...]
"""Returned by the CLOB API in descending price order (highest ask first)."""

Happy to send a small docs PR if welcome.

[cesarenaldi]

Thanks for suggesting this and for the clear write-up.

I opened a small PR to address it here: #45

If the wording and placement in the PR look good to you, I’ll plan to proceed with that approach.