Skip to content

Commit fcbce5e

Browse files
AxonOS-BCIAxonOS-BCI
committed
feat: initial Python SDK — RFC-0006 wire codec + capability model
0 parents  commit fcbce5e

21 files changed

Lines changed: 1406 additions & 0 deletions

‎.github/workflows/ci.yml‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# SPDX-License-Identifier: Apache-2.0 OR MIT
2+
name: CI
3+
4+
on:
5+
push:
6+
branches: [main]
7+
pull_request:
8+
branches: [main]
9+
10+
permissions:
11+
contents: read
12+
13+
concurrency:
14+
group: ci-${{ github.ref }}
15+
cancel-in-progress: true
16+
17+
jobs:
18+
lint:
19+
name: Lint (ruff)
20+
runs-on: ubuntu-latest
21+
steps:
22+
- uses: actions/checkout@v4
23+
- uses: actions/setup-python@v5
24+
with:
25+
python-version: "3.12"
26+
- name: Install ruff (pinned)
27+
run: pip install ruff==0.15.15
28+
- name: ruff check
29+
run: ruff check axonos tests
30+
31+
test:
32+
name: Test (py${{ matrix.python-version }})
33+
runs-on: ubuntu-latest
34+
strategy:
35+
fail-fast: false
36+
matrix:
37+
python-version: ["3.9", "3.10", "3.11", "3.12"]
38+
steps:
39+
- uses: actions/checkout@v4
40+
- uses: actions/setup-python@v5
41+
with:
42+
python-version: ${{ matrix.python-version }}
43+
- name: Install package
44+
run: pip install -e .
45+
- name: Run unit tests
46+
run: python -m unittest discover -s tests -v
47+
48+
build:
49+
name: Build (sdist + wheel)
50+
runs-on: ubuntu-latest
51+
steps:
52+
- uses: actions/checkout@v4
53+
- uses: actions/setup-python@v5
54+
with:
55+
python-version: "3.12"
56+
- name: Install build
57+
run: pip install build
58+
- name: Build distributions
59+
run: python -m build
60+
- name: Upload artifacts
61+
uses: actions/upload-artifact@v4
62+
with:
63+
name: dist
64+
path: dist/*

‎.github/workflows/release.yml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# SPDX-License-Identifier: Apache-2.0 OR MIT
2+
name: Release
3+
4+
on:
5+
push:
6+
tags: ["v*"]
7+
8+
permissions:
9+
contents: write
10+
11+
jobs:
12+
release:
13+
name: Build and publish release
14+
runs-on: ubuntu-latest
15+
steps:
16+
- uses: actions/checkout@v4
17+
- uses: actions/setup-python@v5
18+
with:
19+
python-version: "3.12"
20+
- name: Install build
21+
run: pip install build
22+
- name: Build distributions
23+
run: python -m build
24+
- name: Verify version matches tag
25+
run: |
26+
PKG_VER="v$(python -c 'import axonos; print(axonos.__version__)')"
27+
TAG="${GITHUB_REF_NAME}"
28+
echo "package=$PKG_VER tag=$TAG"
29+
test "$PKG_VER" = "$TAG"
30+
- name: Create GitHub Release
31+
uses: softprops/action-gh-release@v2
32+
with:
33+
files: dist/*
34+
generate_release_notes: true
35+
36+
# --- PyPI publish (opt-in) -------------------------------------------
37+
# Configure a PyPI Trusted Publisher for this repo, add the
38+
# `id-token: write` permission above, then uncomment:
39+
# - uses: pypa/gh-action-pypi-publish@release/v1

‎.gitignore‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
__pycache__/
2+
*.py[cod]
3+
*.egg-info/
4+
.eggs/
5+
build/
6+
dist/
7+
.pytest_cache/
8+
.venv/
9+
.ruff_cache/

‎ABOUT.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# About `axonos-sdk-python`
2+
3+
The Python edition of the AxonOS application boundary. It is a pure-Python,
4+
dependency-free implementation of the RFC-0006 intent-observation wire format
5+
and the capability model, byte-compatible with the reference Rust
6+
[`axonos-sdk`](https://github.com/AxonOS-org/axonos-sdk) for
7+
`KERNEL_ABI_VERSION == 1`.
8+
9+
It exists so that host-side tooling and Python application code can read
10+
kernel observations, declare capability manifests, and round-trip the wire
11+
format without reaching for the Rust toolchain. It does not enforce
12+
capabilities or verify attestations — the kernel does that — and it does not
13+
stub those paths as if it did.
14+
15+
Part of the AxonOS project. See the [organisation](https://github.com/AxonOS-org)
16+
for the kernel, standard, and the rest of the stack.

‎CHANGELOG.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Changelog
2+
3+
All notable changes to `axonos-sdk-python` are documented here.
4+
Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
5+
this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6+
7+
## [0.1.0] — 2026-05-30
8+
9+
### Added
10+
- `IntentObservation` — 32-byte, little-endian RFC-0006 wire codec
11+
(`encode`/`decode`), byte-compatible with the Rust `axonos-sdk` for
12+
`KERNEL_ABI_VERSION == 1`. Layout: `timestamp_us` (u64), `kind_tag` (u16),
13+
`quality_raw` (Q0.16 u16), `payload` ([u8;4]), `session_id` (u64),
14+
`attestation` ([u8;8]).
15+
- `Direction`, `Load`, `Quality` intent kinds; typed `kind` resolution and
16+
`capability()` mapping.
17+
- `Capability`, `CapabilitySet` (little-endian u32 bitfield), `Manifest`
18+
with reserved-bit rejection.
19+
- `MonotonicTimestamp` (saturating arithmetic) and Q0.16 helpers
20+
(`to_raw`, `to_float`).
21+
- 21-test unit suite including cross-language byte vectors for validation
22+
against the Rust reference.
23+
24+
### Not yet implemented (roadmap, intentionally not stubbed)
25+
- Cryptographic attestation verification.
26+
- Typed observation stream and full mesh client.

‎CITATION.cff‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
cff-version: 1.2.0
2+
message: "If you use this software, please cite it as below."
3+
title: "axonos-sdk-python: Python SDK for the AxonOS cognitive operating system"
4+
abstract: >-
5+
Pure-Python implementation of the AxonOS RFC-0006 intent-observation wire
6+
format and capability model, byte-compatible with the reference Rust SDK.
7+
authors:
8+
- family-names: Yermakou
9+
given-names: Denis
10+
email: connect@axonos.org
11+
version: 0.1.0
12+
date-released: 2026-05-30
13+
license: "Apache-2.0 OR MIT"
14+
repository-code: "https://github.com/AxonOS-org/axonos-sdk-python"
15+
url: "https://axonos.org"
16+
keywords:
17+
- brain-computer-interface
18+
- real-time
19+
- capability-security
20+
- rfc-0006

‎CONTRIBUTING.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Contributing
2+
3+
Thanks for your interest in `axonos-sdk-python`.
4+
5+
## Ground rules
6+
7+
- The wire format is **normative**. Any change to `IntentObservation`,
8+
`CapabilitySet`, or the Q0.16 / timestamp encoding must remain byte-for-byte
9+
compatible with the Rust `axonos-sdk` and the kernel's RFC-0006, or be
10+
accompanied by a coordinated ABI-version bump.
11+
- No runtime dependencies. Standard library only.
12+
- Never stub a security path (e.g. attestation) so that it appears present.
13+
An unimplemented guarantee is documented as unimplemented.
14+
15+
## Local checks (the same as CI)
16+
17+
```bash
18+
pip install ruff==0.15.15
19+
ruff check axonos tests
20+
python -m unittest discover -s tests -v
21+
pip install build && python -m build
22+
```
23+
24+
## Cross-language fidelity
25+
26+
If you touch the wire format, regenerate the vectors in
27+
`tests/test_wire.py::TestCrossLanguageVectors` and confirm the same bytes are
28+
produced by the Rust reference before opening a pull request.

0 commit comments

Comments
 (0)