Metadata-Version: 2.4
Name: openbrokers-ibx
Version: 0.0.1.post1
Summary: High-performance async SDK for the Interactive Brokers Gateway API.
Keywords: interactive-brokers,ibkr,trading,async,asyncio,market-data,sans-io,fintech
License-Expression: Apache-2.0
Classifier: Development Status :: 1 - Planning
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Framework :: AsyncIO
Classifier: Typing :: Typed
Requires-Dist: msgspec>=0.21
Requires-Dist: protobuf>=6.31.1
Requires-Dist: click>=8.1 ; extra == 'cli'
Requires-Dist: mcp>=1.0 ; extra == 'mcp'
Requires-Dist: click>=8.1 ; extra == 'mcp'
Requires-Dist: uvloop>=0.19 ; sys_platform != 'win32' and extra == 'perf'
Requires-Dist: pandas>=2.2 ; extra == 'research'
Requires-Dist: polars>=1.0 ; extra == 'research'
Requires-Python: >=3.12
Project-URL: Repository, https://github.com/openbrokers/ibx
Provides-Extra: cli
Provides-Extra: mcp
Provides-Extra: perf
Provides-Extra: research
Description-Content-Type: text/markdown

# ibx

![status: pre-alpha](https://img.shields.io/badge/status-pre--alpha-orange)
![license: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)
![target: python 3.12 | 3.13 | 3.14](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-informational)
[![PyPI](https://img.shields.io/pypi/v/openbrokers-ibx?label=openbrokers-ibx)](https://pypi.org/project/openbrokers-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`](LICENSE). Attribution and lineage (including the
predecessor sources this project derives from) are recorded in [`NOTICE`](NOTICE).
