Metadata-Version: 2.4
Name: i3cex
Version: 0.1.0.dev0
Summary: I3C-EX: Extension layers for MIPI I3C targeting edge AI and edge ML workloads.
Project-URL: Repository, https://github.com/jemsbhai/i3cex-i4c
Project-URL: Specification, https://github.com/jemsbhai/i3cex-i4c/blob/main/specs/I3CEX-0.1.0-draft.md
Project-URL: Issues, https://github.com/jemsbhai/i3cex-i4c/issues
Project-URL: Changelog, https://github.com/jemsbhai/i3cex-i4c/blob/main/i3cex/CHANGELOG.md
Author: Muntaser Syed
License: MIT License
        
        Copyright (c) 2026 Muntaser Syed
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: edge-ai,edge-ml,embedded,i3c,mipi,protocol,sensor-fusion,serial-bus
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: System :: Hardware
Classifier: Typing :: Typed
Requires-Python: >=3.11
Provides-Extra: cosim
Requires-Dist: cocotb-test>=0.2.4; extra == 'cosim'
Requires-Dist: cocotb>=1.9.0; extra == 'cosim'
Provides-Extra: dev
Requires-Dist: hypothesis>=6.120; extra == 'dev'
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pre-commit>=4.0; extra == 'dev'
Requires-Dist: pytest-cov>=6.0; extra == 'dev'
Requires-Dist: pytest-xdist>=3.6; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.27; extra == 'docs'
Provides-Extra: sim
Description-Content-Type: text/markdown

# i3cex

Extension layers for MIPI I3C targeting edge AI and edge ML workloads.

> **Pre-alpha**. Specification and implementation are in flux.
> Developmental releases are available on
> [PyPI](https://pypi.org/project/i3cex/). See the
> [current specification draft](https://github.com/jemsbhai/i3cex-i4c/blob/main/specs/I3CEX-0.1.0-draft.md).

## What is I3C-EX?

I3C-EX is a set of optional, backward-compatible extension layers atop
MIPI I3C. It adds metadata envelopes, QoS negotiation, Byzantine fusion
signalling, distributed timestamping, provenance/attestation, and
confidence propagation — all as optional sublayers that run on existing
I3C hardware with firmware updates only.

See the repository's
[top-level README](https://github.com/jemsbhai/i3cex-i4c/blob/main/README.md)
for project motivation and dual-track strategy, and
[GOVERNANCE.md](https://github.com/jemsbhai/i3cex-i4c/blob/main/GOVERNANCE.md)
for development standards.

## Installation

```bash
pip install --pre i3cex                   # core library
pip install --pre "i3cex[sim]"            # with pure-Python simulator extras
pip install --pre "i3cex[cosim]"          # with cocotb cosimulation (Linux/WSL2)
pip install --pre "i3cex[dev]"            # development tooling
```

## Development

### Prerequisites

- Python 3.11 or later (3.12+ recommended).
- [Hatch](https://hatch.pypa.io/) for environment management
  (`pipx install hatch`).
- For cosimulation only: Linux or WSL2, Verilator 5.012+, Icarus Verilog 12.0+.

### Setup

```bash
# From repository root:
cd i3cex

# Create the dev environment
hatch env create

# Run unit and property tests
hatch run test

# Run full test suite with coverage
hatch run cov

# Run linter
hatch run lint

# Run type checker
hatch run typecheck

# Run all quality checks
hatch run check
```

### Project Structure

```
i3cex/
├── pyproject.toml              Hatch-based build configuration
├── README.md                   This file
├── LICENSE                     MIT
├── CHANGELOG.md                Keep-a-changelog format
├── .gitignore
├── .pre-commit-config.yaml     Ruff + mypy on every commit
├── src/
│   └── i3cex/
│       ├── __init__.py         Package root, version exported
│       ├── py.typed            PEP 561 marker
│       ├── framing/            Wire-level framing strategies
│       │   ├── __init__.py
│       │   ├── preamble.py     Candidate A: preamble header codec
│       │   └── tlv.py          Candidate B: TLV framing
│       ├── envelope/           EX-1: metadata envelope sublayer
│       │   └── __init__.py
│       ├── qos/                EX-2: quality-of-service (stub)
│       │   └── __init__.py
│       ├── fusion/             EX-3: Byzantine fusion signalling (stub)
│       │   └── __init__.py
│       ├── timesync/           EX-4: distributed timestamping (stub)
│       │   └── __init__.py
│       ├── provenance/         EX-5: provenance/attestation (stub)
│       │   └── __init__.py
│       ├── confidence/         EX-6: confidence propagation (stub)
│       │   └── __init__.py
│       └── sim/                Pure-Python I3C/I3C-EX simulator
│           └── __init__.py
├── tests/
│   ├── unit/                   Fast pure-function tests
│   ├── property/               Hypothesis-based generative tests
│   ├── integration/            Multi-component, uses sim
│   ├── cosim/                  cocotb tests vs chipsalliance/i3c-core RTL
│   └── vectors/                Normative test vectors (spec conformance)
└── docs/
    └── adr/                    Architecture Decision Records
```

## Testing Philosophy

See
[GOVERNANCE.md](https://github.com/jemsbhai/i3cex-i4c/blob/main/GOVERNANCE.md)
for the full statement. Summary:

- **Strict TDD.** No implementation code lands without a failing test first.
- **Four test layers.** Unit, property, integration, cosim.
- **Coverage targets.** 95%+ line / 90%+ branch for core; 85%+ for
  utility; 80%+ for sim.
- **Property tests are mandatory for parsers and framers.** Every wire
  format decoder MUST have a `hypothesis` roundtrip test.
- **Pre-registered specifications.** The spec in `../specs/` is written
  first; code tracks the spec.

## Sublayer Roadmap

I3C-EX sublayers are implemented sequentially:

1. **EX-1 metadata envelope** — in progress (v0.1.0).
2. **EX-2 QoS negotiation** — after EX-1 stabilises.
3. **EX-3 Byzantine fusion** — after EX-2.
4. **EX-4 distributed timestamping** — after EX-3.
5. **EX-5 provenance/attestation** — after EX-4.
6. **EX-6 confidence propagation** — after EX-5.

Framing strategy (preamble-byte vs TLV) is chosen empirically before
EX-1 stabilises; see
[I3CEX-0.1.0-draft.md](https://github.com/jemsbhai/i3cex-i4c/blob/main/specs/I3CEX-0.1.0-draft.md)
section 5.

## License

MIT. See the
[license](https://github.com/jemsbhai/i3cex-i4c/blob/main/i3cex/LICENSE).
