Optimize client performance hot paths

[terjekv]

Summary

• lazily initialize the synchronous and asynchronous HTTPX clients so sync-only and async-only users do not pay for an unused transport
• streamline authorization request/context serialization and batch response parsing
• build repeated policy-filter query parameters in one pass
• reduce overhead in user/group construction and batch aggregate helpers
• add lifecycle and many-filter CodSpeed coverage plus lazy-initialization regression tests

Why

Client construction eagerly created both HTTPX stacks, including TLS and connection-pool setup, even when callers only used one API style. The model hot paths also repeated regex work, timestamp parsing, enum dispatch, error-path formatting, immutable query rebuilding, and small helper calls across every batch item.

Performance

Local CPython 3.13 microbenchmarks (median of 7 repeats):

Workload	Before	After	Change
Unused client create + close	53.57 ms	0.72 µs	>99.99% faster
Serialize 100 contextual requests	1,494.53 µs	1,170.56 µs	21.7% faster
Parse 100 brief results	577.22 µs	506.45 µs	12.3% faster
Parse 50 detailed results	397.24 µs	328.08 µs	17.4% faster
Build a user with 200 groups	360.03 µs	297.42 µs	17.4% faster
Run all three aggregates over 100 results	36.79 µs	19.12 µs	48.0% faster
Build 120 repeated policy filters	277.52 µs	30.60 µs	89.0% faster

The new end-to-end CodSpeed cases measure first sync request lifecycle at ~27.2 ms and a mocked policy request with 120 filters at ~1.4 ms.

Validation

• .venv/bin/pytest -m 'not integration' — 85 passed
• .venv/bin/pyright — clean
• .venv/bin/basedpyright — clean
• targeted CodSpeed lifecycle and many-filter benchmarks — passed
• git diff --check — clean

[codspeed]

Merging this PR will improve performance by 26.89%

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 13 improved benchmarks
✅ 16 untouched benchmarks
🆕 2 new benchmarks

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
⚡	test_authorize_response_aggregates	745.9 µs	290.3 µs	×2.6
⚡	test_user_policies_from_api	984.3 µs	709.2 µs	+38.78%
⚡	test_user_new_many_groups	5.2 ms	4.1 ms	+27.21%
⚡	test_batch_to_api[100]	18.6 ms	14.7 ms	+26.41%
⚡	test_request_to_api_with_context	261.6 µs	214.2 µs	+22.13%
⚡	test_authorize_response_detailed_from_api[50]	5.4 ms	4.5 ms	+21.26%
⚡	test_serialize_authorization_batch_128	14.3 ms	11.8 ms	+20.93%
⚡	test_batch_to_api[1]	267.1 µs	228.2 µs	+17.05%
⚡	test_parse_brief_authorization_response_128	10.4 ms	9.1 ms	+14.72%
⚡	test_authorize_response_detailed_from_api[1]	212 µs	185 µs	+14.6%
⚡	test_metadata_from_api	99.9 µs	88.8 µs	+12.43%
⚡	test_authorize_response_brief_from_api[100]	7.5 ms	6.7 ms	+11.97%
⚡	test_version_response_from_api	139.3 µs	125.4 µs	+11.09%
🆕	test_first_sync_request_lifecycle	N/A	156.1 ms	N/A
🆕	test_list_policies_many_filters	N/A	14.2 ms	N/A

Tip

Curious why this is faster? Comment @codspeedbot explain why this is faster on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing agent/deep-performance-pass (215a68c) with main (0a425a4)}