openbrokers-ibx 0.0.1.post1

High-performance async SDK for the Interactive Brokers Gateway API.

ibx

Pre-alpha. The PyPI name is claimed with a minimal placeholder (openbrokers-ibx 0.0.1 — no functionality). There is no usable public API yet; the first real release is planned as 0.1.0.

What ibx is

A high-performance, async-first Python SDK for the Interactive Brokers Gateway local API, built from scratch around one strict architectural rule: the protocol core does no I/O, holds no clock, and never imports asyncio. Everything else — asyncio shell, blocking facade, native acceleration, replay tooling — is a host driving that pure core.

Design pillars

• Sans-I/O protocol core. The wire protocol is a pure state machine: feed bytes in, get typed events out, ask it when its next deadline is. That makes the protocol testable as plain functions, fuzzable, replayable offline, and hostable from asyncio, blocking sockets, or native code without reimplementation.
• IB's real 2026 wire, day one. Modern Gateways (≥ 10.30) speak a hybrid wire — protobuf for migrated message types, legacy field-delimited text for the rest. ibx decodes both behind a single frozen event vocabulary, keyed per message type.
• Order safety by construction. Every IB error code is classified as data (Warning / Rejection / Connectivity / Pacing). A warning can never resolve an order's completion. A send either reaches the kernel buffer or raises — never a silent void. A corrupt wire field is counted and dropped, never coerced into a plausible number.
• Rust-accelerated hot path (planned, milestone M3). A whole-loop native core — socket → framing → decode → event ring, one GIL crossing per batch — with a permanent pure-Python fallback and byte-for-byte parity between the two, enforced in CI.
• Typed, minimal API surface (planned, M2/M5). An asyncio-first IB facade and a generated, fully-typed blocking IBSync; subscriptions are async iterators; .df()/.pl() conversions for research; record/replay for deterministic offline work; an MCP server for AI agents with hard, code-enforced safety rails (read-only by default; live trading refused unconditionally).
• Claim honesty. A feature or performance number appears in this README only once a CI gate executes it. Benchmark claims will arrive with the published, reproducible benchmark suite — not before.

What exists today

Each item below is exercised by tests in CI on CPython 3.12, 3.13 and 3.14:

• Length-prefixed framing — round-trips a golden corpus of 561 recorded Gateway frames byte-for-byte; survives arbitrary fuzzed input without raising; corrupt length prefixes are counted and skipped; 100% branch coverage.
• Frozen event vocabulary — immutable msgspec structs for inbound events and outbound requests; absent or corrupt numeric fields decode to None, never to a fabricated 0.0.
• Error taxonomy — a data table (not if-chains) classifying every error code observed in the corpus, with a conservative default for unknown codes.
• Connection state machine — completes the full handshake against real captured Gateway traffic, fragmented at arbitrary byte boundaries; enforces the minimum Gateway version; expresses liveness (idle → ping → dead) as pure deadline arithmetic.
• Legacy text codec — data-driven dispatch table decoding the corpus's message inventory deterministically; unknown message types are explicitly counted, never silently dropped.
• Test infrastructure — an in-repo asyncio mock Gateway speaking the full handshake, plus the golden corpus with an integrity-checked manifest.

Roadmap (abridged)

protocol core hardening (fuzz + 100% protocol coverage) → asyncio shell, market data and published end-to-end benchmarks vs ib_async → Rust whole-loop core with parity gates → order management and supervised reconnection (paper-tier nightly conformance) → research tooling and MCP → docs, CLI, containers → 0.1.0 on PyPI via Trusted Publishing with attestations.

The final distribution name will be settled before 0.1.0 (a PEP 541 request for the name ibx is pending; openbrokers-ibx is the fallback). The import name is ibx in every scenario.

License

Apache License 2.0 — see LICENSE. Attribution and lineage (including the predecessor sources this project derives from) are recorded in NOTICE.