Metadata-Version: 2.4
Name: oai-python
Version: 0.4.0
Summary: Python bindings for pinned OpenAirInterface telecom capabilities
Author: Joao
License-File: LICENSE
License-File: bindings/licenses/OAI-CSSL-v1.0.txt
License-File: bindings/licenses/OAI-NOTICE.txt
License-File: bindings/licenses/OAI-PYTHON-MODIFICATIONS.txt
License-File: bindings/licenses/OpenSSL-Apache-2.0.txt
License-File: bindings/licenses/SIMDe-MIT.txt
License-File: bindings/licenses/asn1c-BSD-2-Clause.txt
License-File: bindings/licenses/open-nFAPI-Apache-2.0.txt
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Project-URL: Homepage, https://github.com/jmoraispk/oai-python
Project-URL: Documentation, https://jmoraispk.github.io/oai-python/
Project-URL: Repository, https://github.com/jmoraispk/oai-python
Project-URL: Issues, https://github.com/jmoraispk/oai-python/issues
Project-URL: Changelog, https://github.com/jmoraispk/oai-python/blob/main/CHANGELOG.md
Requires-Python: >=3.12
Requires-Dist: numpy>=2.2
Provides-Extra: dev
Requires-Dist: numpy>=2.2; extra == "dev"
Requires-Dist: torch>=2.13.0; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: ty; extra == "dev"
Requires-Dist: PyYAML>=6.0; extra == "dev"
Requires-Dist: rich>=13.7.0; extra == "dev"
Requires-Dist: mkdocs>=1.6; extra == "dev"
Requires-Dist: mkdocs-material>=9.5.0; extra == "dev"
Requires-Dist: pymdown-extensions>=10.5; extra == "dev"
Requires-Dist: tree-sitter>=0.24; extra == "dev"
Requires-Dist: tree-sitter-c>=0.24; extra == "dev"
Requires-Dist: jsonschema>=4.23; extra == "dev"
Description-Content-Type: text/markdown

# oai-python

[![Release 0.4.0](https://img.shields.io/badge/release-0.4.0-0b7285)](https://github.com/jmoraispk/oai-python/releases)
[![Python 3.12–3.14](https://img.shields.io/badge/Python-3.12%E2%80%933.14-3776ab)](https://pypi.org/project/oai-python/)
[![Linux x86-64](https://img.shields.io/badge/platform-Linux%20x86--64-495057)](https://jmoraispk.github.io/oai-python/platform-support/)
[![Docs: online](https://img.shields.io/badge/docs-online-2f9e44)](https://jmoraispk.github.io/oai-python/)
[![License: CSSL 1.0](https://img.shields.io/badge/license-CSSL%201.0-7950f2)](https://github.com/jmoraispk/oai-python/blob/main/LICENSE)

`oai-python` 0.4 is a MIMO-first, offline, in-memory 5G NR PHY product. It
embeds reviewed OpenAirInterface operations behind semantic Python endpoints
and inspectable stages; it is not the OAI NR softmodem or a Python port.

```python
from oai_python import Gnb, Ue, Cell, MultiCell
from oai_python import RadioChannel, IdentityRadioChannel
```

## Install

```console
uv add oai-python==0.4.0
```

<!-- BEGIN OAI-PYTHON RELEASE STATUS -->
<!-- END OAI-PYTHON RELEASE STATUS -->

## The offline radio model

The endpoint/channel boundary has three phases:

```python
transmissions = gnb.transmit(frame, slot)
receptions = channel.propagate(transmissions)
result = ue.receive(receptions)
```

Use `Gnb` and `Ue` for the coarse endpoint route. Use `GnbPipeline` and
`UePipeline` to execute the corresponding public stages one by one and inspect
owned checkpoints. The two routes share a functional comparison contract; the
coarse route avoids repeated Python/native boundary crossings.

`Cell` owns one gNB, one or more UEs, and optionally its channel. `MultiCell`
combines channel-free cells around one shared, batch-shaped channel call. The
supplied `IdentityRadioChannel` is deterministic and has no impairments.

## MIMO-first PHY slots

The caller selects downlink and uplink links, allocation, rank, PMI, MCS,
explicit HARQ fields, and CSI-RS/SRS occasions in one `PhySlotPlan`.
`Cell.run_phy(plan)` executes all endpoint phases with one channel propagation.
MIMO waveform and estimate arrays retain explicit port, chain, and I/Q axes.
CSI-RS reports expose RI, PMI, SINR, CQI, and channel estimates; SRS reports
expose SNR, timing, and channel estimates. These receiver estimates remain
distinct from channel truth in `ChannelObservation`.

The direct route minimizes Python/native crossings. The staged route exposes
owned intermediate checkpoints, and `compare_phy_slot_routes` verifies the
two independently owned executions against one propagated batch.

HARQ state and combining are explicit: callers choose process IDs, new data,
and legal redundancy versions. Automatic HARQ and adaptive scheduling are not
part of 0.4. NAS registration, a core network, coupled multicell interference,
mobility, handover, RF hardware, and real-time operation remain outside scope.

Sionna is not bundled. The general `RadioChannel` protocol is designed for a
future Sionna ray-tracing adapter. Version 0.4 provides structural multicell
orchestration, not coupled inter-cell interference, mobility, handover, RF
hardware, or an attached core network.

## Documentation

- [Quickstart](docs/quickstart.md)
- [Offline radio model](docs/OFFLINE_RADIO_MODEL.md)
- [Generated public stage reference](docs/BINDINGS_API_REFERENCE.md)
- [MIMO PHY slots](docs/examples/mimo.md)
- [Measurement dashboard example](docs/examples/mimo-measurements.md)
- [Stable 0.4 API contract](docs/BINDINGS_STABLE_API.md)
- [0.2-to-0.3 migration ledger](docs/BINDINGS_API_MIGRATION_0_3.json)
- [0.4 performance contract](docs/BINDINGS_0_4_PERFORMANCE.md)

<!-- BEGIN OAI PIN PROVENANCE (verified by tests/test_oai_pin.py) -->
Built from [OpenAirInterface 2026.w35 at `ceccfc8ffa4340d5bdc08a9fc84d2e6ab3f9472c`](https://github.com/OPENAIRINTERFACE/openairinterface5g/commit/ceccfc8ffa4340d5bdc08a9fc84d2e6ab3f9472c)
with [SIMDe `1c68d9ad60bf63f3fb527c4ee3b2319d828ffcc6`](https://github.com/simd-everywhere/simde-no-tests/commit/1c68d9ad60bf63f3fb527c4ee3b2319d828ffcc6).
<!-- END OAI PIN PROVENANCE -->

The project and compiled OAI code use the Collaborative Standards Software License.
