Feat/truncate text and cross parent reads

[loookashow]

Types and plumbing for two Flux API features that shipped server-side: response truncation on reads, and cross-parent read addresses for strict-reference collections.

Flux

truncate_text is reachable from search(). FluxClient.search() / AsyncFluxClient.search() accept a keyword-only params mapping forwarded to the query string. The transport already supported query parameters; they were simply not plumbed through search(). With the existing passthrough on list_resources(), both List Resources and Search now support it.

truncate_text is an integer ≥ 1 that caps every text-typed field and is ignored when raw=true. Truncated fields are marked under _sys.truncated (field, locale — null for non-localized — and original_length); fields within the limit get no entry. No client-side validation: an invalid value surfaces as a server 422 validation_error.

query_params on the four search wrappers — vector_search(), vector_field_search(), hybrid_search(), boosted_search(), sync and async. Named query_params rather than params deliberately: params was already meaningful inside **extra_body (forwarded to the JSON body), so an explicit params keyword would have silently rerouted it to the query string for any caller already passing params={...} as a search-body field. _merge_extra now raises if handed truncate_text as a body field and names query_params as the right place for it.

Management

Cross-parent (flat) read addressing for strict-reference collections. add_api_collection / update_api_collection (and the deprecated add_api_folder / update_api_folder), sync and async, accept unscoped_levels: list[int] and unscoped_ancestors: list[str]. These expose additional read-only addresses that drop the ancestor chain entirely (level == 0) or partially (level >= 1, keeping the root-most keys).

The API requires both to be sent together. Not enforced client-side — the server owns that rule and may relax it.

Typed connection fields. APIFolderSummary (aliased APICollectionSummary) gains unscoped_levels, unscoped_ancestors, expose_owner — all defaulting to an empty/false value if the server omits them — plus flat_route and flat_routes, both optional and nullable, since null was observed on connections with no key-bearing ancestor. New FlatRoute and FlatRouteSummary models.

APIFolderSummary and both new models set model_config = ConfigDict(extra="allow"), so unrecognised fields — present or future — are preserved rather than silently dropped.

Not in scope: cross-parent writes. FluxClient has no create/update taking a folder path beyond the documented ones, and the server rejects writes on flat paths regardless. List, Get Resource and Schema already worked against these addresses, because the collection path is an opaque slash-trimmed string; this only adds typed support for the connection object and for configuring the addresses.

Fixed

DEFAULT_USER_AGENT was pinned to foxnose-sdk/0.1.0 regardless of the installed version — every request from every release reported 0.1.0. The version now lives in a single _version.py imported by both foxnose_sdk/__init__.py (so foxnose_sdk.__version__ keeps working) and config.py (so the User-Agent is real), which is what avoids the circular import that motivated the stale constant in the first place.

Repo hygiene

• CI now gates the whole repo (ruff check . / ruff format --check .) instead of src/ only. Linting src/ alone let tests/ drift until it needed a repo-wide reformat to get back in line — that reformat is the style: commit here.
• .claude/ is gitignored, as it already is in core, delivery-api, integration-tests and ts-sdk. Without it the repo-wide gate walks untracked tool directories and fails on code that is not in the repository.
• An opt-in pre-push hook so the same gates can run before a push rather than after.

Review the formatting commit separately from the feature commits — it touches many files and changes nothing.

Known server-side discrepancies, typed as sent

Not worked around in the SDK, and raised with the API team:

• flat_routes[].read_methods reports ["get_one", "get_many"] at level 0, though the docs describe Get Resource as available only at level >= 1.
• read_methods never includes search at any level, though the docs list Search as available on flat addresses.

read_methods is typed as the server sends it rather than as documented.

Tests

Full suite green; ruff check . and ruff format --check . clean.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!