Metadata-Version: 2.4
Name: oai-python
Version: 0.1.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.1.0](https://img.shields.io/badge/release-0.1.0-0b7285)](https://github.com/jmoraispk/oai-python/releases)
[![Python 3.12–3.14t](https://img.shields.io/badge/Python-3.12%E2%80%933.14t-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/support-and-scope/)
[![Documentation](https://github.com/jmoraispk/oai-python/actions/workflows/docs.yml/badge.svg)](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)
High-performance, typed Python bindings for OpenAirInterface 5G NR. Use real
OAI physical-layer blocks, run persistent link and stack simulations, or test a
scheduler from one Python application—without managing separate UE and gNB
terminals.

Release `0.1.x` is the bindings-only release for Linux x86-64. It does not install PyTorch or select another backend at runtime.

## Install

```bash
uv add oai-python==0.1.0
uv run oai-python-diagnose
```

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

## A complete PHY link

```python
from oai_python.bindings.nr.phy.link import NrPhyLink

payload = bytes(range(64))
with NrPhyLink() as link:
    slot = link.step(downlink_payload=payload)
    link.run_slots(100)

(received,) = slot.transmissions
assert received.crc_ok and received.decoded_payload == payload
print(f"decoded {len(received.decoded_payload)} downlink bytes")
```

`NrPhyLink` owns the OAI state across every requested slot. The same process
can also run a one-UE real-PHY stack, a 1–16 UE MAC/FAPI simulation, or several
independent cells. See the [Quickstart](https://jmoraispk.github.io/oai-python/quickstart/)
for the differences.

## Coverage

| Public surface | Coverage in 0.1 |
| --- | ---: |
| Supported workflows | 42 exports |
| Supported granular/shared capabilities | 476 exports |
| Additional reference-only OAI inventory | 1,189 exports |
| Default NR wheel | 1,707 exports across 272 leaf modules |

Supported areas include NR PHY, coding, MAC, RLC, PDCP, SDAP, RRC,
NAS/security, FAPI/nFAPI, signaling, and O-RAN value/codecs. An importable name
does not by itself imply a supported end-to-end workflow; the
[coverage guide](https://jmoraispk.github.io/oai-python/coverage-performance/)
explains the three tiers.

## Performance per slot

Warm steady-state latency on the release benchmark host. Each row compares an
identical workload at the direct-C and public Python-call boundaries; rows do
different telecom work and must not be compared with one another.

<!-- BEGIN GENERATED OAI-PYTHON PERFORMANCE TABLE -->
| Workload per slot | Timing boundary | Original pinned OAI (direct C) | Python bindings (public call) |
| --- | --- | ---: | ---: |
| Connected gNB MAC slot | one loaded scheduler slot | 5.08 us p50; 6.26 us p95 | 235.21 us p50; 249.47 us p95 |
| FR1 SISO PUSCH receive | estimation through demodulation for one frequency-domain slot | 185.81 us p50; 194.54 us p95 | 985.10 us p50; 1032.57 us p95 |
<!-- END GENERATED OAI-PYTHON PERFORMANCE TABLE -->

The [benchmark methodology](https://jmoraispk.github.io/oai-python/coverage-performance/#performance)
defines the exact geometry, warm-up, repetitions, hardware, equivalence checks,
and timing boundaries. No general sub-millisecond claim is made beyond a named
measured row.

## Choose a simulation boundary

| Mode | Use it for |
| --- | --- |
| Granular PHY | Calling or replacing one real OAI coding, modulation, estimation, or receiver block |
| Full-PHY link | Link-level SISO waveform experiments without MAC |
| Full-PHY stack | One-UE access and traffic where MAC grants drive real PHY paths |
| MAC/FAPI | Fast 1–16 UE scheduler and protocol simulation with abstracted PHY outcomes |
| Independent cells | Several isolated simulations in one Python application |

The ordinary OAI scheduler is the default fast path. A Python policy can opt
into a decision seam connected to the real PHY stack. External channel models
use copied time-domain IQ samples; the wheel provides the insertion point, not
a propagation model. The optional [Sionna RT example](https://jmoraispk.github.io/oai-python/examples/sionna-rt/)
shows OAI waveform → user-owned channel → OAI receiver without making Sionna a
dependency.

## Requirements and limits

- Linux x86-64 with glibc 2.28 or newer.
- Regular CPython 3.12 or newer through one ABI3 wheel, plus a distinct
  free-threaded CPython 3.14t wheel.
- Reviewed offline/in-memory 5G NR SA profile: FR1 band 78, numerology 1,
  106 resource blocks, and SISO.

## What is excluded?

The 0.1 wheel does not include alternative Python implementations, propagation
models, Sionna RT, native/custom CUDA, RF/UHD/DPDK execution, an attached 5G
core, or live E2/O-RAN runtime integration. It does not claim LTE/EPC/NSA,
MIMO, mobility/handover, coordinated inter-cell interference, Windows, macOS,
or ARM support. Sionna RT and other channel models remain optional user-owned
Python around the bindings' time-domain IQ insertion point.

<!-- 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 -->

## Documentation and support

[Quickstart](https://jmoraispk.github.io/oai-python/quickstart/) ·
[Examples](https://jmoraispk.github.io/oai-python/examples/phy-link/) ·
[Supported API](https://jmoraispk.github.io/oai-python/reference/api/) ·
[Platform support](https://jmoraispk.github.io/oai-python/platform-support/) ·
[Issue tracker](https://github.com/jmoraispk/oai-python/issues) ·
[Security policy](https://github.com/jmoraispk/oai-python/blob/main/SECURITY.md)

The project and compiled OAI code use the Collaborative Standards Software License; bundled third-party components retain their own notices.
