Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
source files, and test files, and skips symlinked entries even when local
search is configured to follow symlinks.

### Python distribution

- The native Python package was separately published to PyPI as
`eggsearch==0.4.4` on 2026-10-28, with CPython 3.11–3.15 ABI3 wheels for
Linux x86_64/aarch64, macOS x86_64/arm64, Windows x86_64, and experimental
ARMv7 hard-float Linux.

## [0.4.3] - 2026-10-13

### Fixed
Expand Down
19 changes: 16 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,19 @@ Pin a version, or install from source with `cargo install eggsearch --locked`. T
installer verifies a SHA-256 checksum and the version, and never elevates — see
[Installation](docs/installation.md) for targets and fallback rules.

Install the native asyncio Python package separately:

```bash
python -m pip install eggsearch
```

On ARMv7 SBCs, require a prebuilt wheel so unsupported targets fail without
attempting a source build:

```bash
python -m pip install --only-binary=:all: eggsearch
```

## Quickstart

```bash
Expand Down Expand Up @@ -147,9 +160,9 @@ See [Safety](docs/safety.md) and [Threat model](docs/threat-model.md).
[CodeGG harness integration](docs/codegg-integration.md) ·
[Test inventory](docs/test-inventory.md)

The in-process asyncio Python package is under `bindings/python` and is not
published yet. See the [Python library guide](docs/python-library.md) for
local build instructions and current support limits.
The in-process asyncio Python package is published separately on PyPI. See the
[Python library guide](docs/python-library.md) for its API, platform limits,
and experimental ARMv7 SBC support.

## Build

Expand Down
34 changes: 18 additions & 16 deletions architecture/python-library.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,13 +19,13 @@ superseded as the qualification basis by M008 advisory remediation and
symlink containment at `plans/closure/python-native-library/008-status.md`
(candidate `067468a`, fully-green run `38641009246`).

A separate **active PyPI distribution workstream** (not a reopening of M001–M008)
is registered at `plans/subsystems/python-pypi-distribution-roadmap.md`.
It prepares CPython 3.11–3.15 ABI3 support, hosted prebuilt ARMv7/SBC wheels,
first controlled PyPI publication, and **post-publication** physical-SBC
benchmarking. No device-local source build or native SBC benchmark is a
first-release prerequisite; compatible SBC installs must use the published
prebuilt wheel and are labeled experimental pending hardware evidence.
A separate PyPI distribution workstream (not a reopening of M001–M008) is
registered at `plans/subsystems/python-pypi-distribution-roadmap.md`. M003
published `eggsearch==0.4.4` with CPython 3.11–3.15 ABI3 support and hosted
prebuilt ARMv7 wheels. M004 covers **post-publication** physical-SBC
benchmarking. No device-local source build or native SBC benchmark was a
first-release prerequisite; ARMv7 installs use the published prebuilt wheel
and remain experimental pending hardware evidence.


## Rust operation facade
Expand Down Expand Up @@ -70,19 +70,21 @@ out with `debug_assertions` off and never ships in release wheels.
Milestone status and exact-candidate evidence live in
`plans/registry.md` and `plans/closure/python-native-library/`. A compiled
extension alone is not evidence of a supported Python consumer. Wheel support
is limited to targets with native install and runtime qualification, and
publication requires separate authorization.
is limited to targets with native install and runtime qualification. Python
publication is separate from Rust crate and Eggpack binary releases and uses
the manually dispatched OIDC workflow.

The active PyPI distribution candidate uses PyO3's `abi3-py311` stable ABI.
Its release matrix builds a manylinux2014 Linux x86_64/aarch64 wheel, macOS
x86_64/arm64 wheels, and a Windows x86_64 wheel, then installs each exact
artifact on CPython 3.11–3.15 in separate consumer jobs. These platform claims
remain conditional on the matching exact-candidate matrix jobs passing. An sdist
The published PyPI distribution uses PyO3's `abi3-py311` stable ABI. Its
release matrix built a manylinux2014 Linux x86_64/aarch64 wheel, macOS
x86_64/arm64 wheels, a Windows x86_64 wheel, and an experimental ARMv7
hard-float wheel; all six passed exact-candidate qualification and public
binary-only consumer installs. An sdist
rebuild uses the binding and root Cargo manifests from clean extraction; it can
build offline with locked crates already cached, otherwise Cargo registry
access is required. PyPy, free-threaded CPython, and Windows ARM64 are outside
the support matrix. ARMv7 requires its separate experimental wheel and
emulated installed-wheel qualification before it may be listed as supported.
the support matrix. ARMv7 has an experimental `manylinux_2_28_armv7l`
hard-float wheel with emulated public installation; physical hardware evidence
is pending through M004.

The public Python `AsyncEggsearch` wrapper adds `async with`, `aclose()`, and
the ten named keyword methods over the generic native `execute` call. Request
Expand Down
17 changes: 15 additions & 2 deletions bindings/python/PYTHON_README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,21 @@ The native package exposes an asyncio client for Eggsearch's ten search,
fetch, repository, security, research, diagnostic, and evidence operations.
It calls the shared Rust SDK in-process and does not start the MCP server.

This package is not published to PyPI. To build and install it locally, use
Rust 1.89, CPython 3.11–3.15, and an active virtual environment:
Install the published package with pip:

```bash
python -m pip install eggsearch
```

ARMv7 SBC support is experimental; require a prebuilt wheel and do not build
the source distribution on-device:

```bash
python -m pip install --only-binary=:all: eggsearch
```

To build and install from this checkout for development, use Rust 1.89,
CPython 3.11–3.15, and an active virtual environment:

```bash
python -m venv .venv
Expand Down
7 changes: 7 additions & 0 deletions bindings/python/benchmarks/sbc_runtime.py
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,9 @@

from eggsearch import AsyncEggsearch, EggsearchError, tool_names

QUALIFIED_VERSION = "0.4.4"
QUALIFIED_SOURCE_SHA = "1135608af5d625cd72db6704adf3bcabd1a58ab1"


def percentile(values, fraction):
ordered = sorted(values)
Expand Down Expand Up @@ -311,11 +314,14 @@ def run_sequential_event_loop_benchmark(config, repeats):
def main():
parser = argparse.ArgumentParser()
parser.add_argument("--version", required=True)
parser.add_argument("--source-sha", required=True)
parser.add_argument("--repeats", type=int, default=40)
parser.add_argument("--wheel", type=Path, required=True)
parser.add_argument("--pip-report", type=Path, required=True)
parser.add_argument("--output", type=Path, default=Path("sbc-runtime.json"))
args = parser.parse_args()
if args.version != QUALIFIED_VERSION or args.source_sha != QUALIFIED_SOURCE_SHA:
raise SystemExit("version or source SHA does not match the M003-qualified PyPI candidate")
installed = distribution("eggsearch")
if installed.version != args.version:
raise SystemExit(f"installed eggsearch {installed.version} does not match {args.version}")
Expand Down Expand Up @@ -374,6 +380,7 @@ def main():
raise SystemExit("installed package did not expose ten unique tool names")
result = {
"package_version": installed.version,
"qualified_source_sha": args.source_sha,
"wheel": str(args.wheel),
"wheel_sha256": wheel_sha256,
"pypi_wheel_url": download["url"],
Expand Down
31 changes: 25 additions & 6 deletions docs/installation.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,31 @@
# Installation

## Python package

The in-process native Python package is published separately from the Rust
crate and executable assets. Install it on a supported host with:

```bash
python -m pip install eggsearch
```

On ARMv7 or another SBC, require a prebuilt compatible wheel so an unsupported
host fails without compiling the source distribution:

```bash
python -m pip install --only-binary=:all: eggsearch
```

The published package supports CPython 3.11–3.15. Linux x86-64 and aarch64
wheels use manylinux2014 (glibc 2.17); the experimental ARMv7 hard-float wheel
requires glibc 2.28 or newer. macOS x86-64/arm64 and Windows x86-64 wheels are
also available. See the [Python library guide](python-library.md) for API and
platform details. ARMv7 remains experimental pending physical SBC measurements.

## Install from the published binary release

The `v0.4.3` release candidate is prepared to carry the Mode-Off local
repository dispatch fix. Until it is published, `v0.4.2` remains the latest
published release. `v0.3.9` was the first binary-enabled release and `v0.4.0`
is crate + tag only, with no published binaries. Once published, install the
host-matched executable with the reviewed release installer:
The Rust executable release is separate from the Python package. Install the
host-matched executable with the release installer:

```bash
curl -fsSL https://github.com/eggstack/eggsearch/releases/latest/download/install.sh | bash
Expand All @@ -18,7 +37,7 @@ PowerShell:
irm https://github.com/eggstack/eggsearch/releases/latest/download/install.ps1 | iex
```

Pin a published binary version when reproducibility matters:
Pin a published executable version when reproducibility matters:

```bash
curl -fsSL https://github.com/eggstack/eggsearch/releases/latest/download/install.sh | bash -s -- --version 0.4.3
Expand Down
71 changes: 39 additions & 32 deletions docs/python-library.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,19 @@
The native Python package wraps the same Rust SDK operations used by Eggsearch's
MCP tools. It runs in-process and does not launch an Eggsearch executable, MCP
server, or listener. The package is an independent PyO3 extension under
`bindings/python`; it is not published to PyPI yet.
`bindings/python` and is published separately from the Rust crate and binaries.

Install it from PyPI:

```bash
python -m pip install eggsearch
```

On ARMv7 SBCs, require a compatible prebuilt wheel:

```bash
python -m pip install --only-binary=:all: eggsearch
```

## Build and use locally

Expand All @@ -19,12 +31,10 @@ python -m pytest -q bindings/python/tests
pyright bindings/python/python/eggsearch bindings/python/examples
```

No Python runtime dependencies are required. The candidate distribution and
import name are both `eggsearch`, and the Python package version tracks the root
Eggsearch version as a starting point for synchronized candidate artifacts.
PyPI's project JSON endpoint returned 404 for `eggsearch` on 2026-10-14. The
package remains unpublished, and name availability must be rechecked
immediately before any separately authorized publication.
No Python runtime dependencies are required. The distribution and import name
are both `eggsearch`. The first public Python distribution is version 0.4.4;
Python package publication is a separate release from the Rust crate and
Eggpack binary assets.

## Client API

Expand Down Expand Up @@ -122,24 +132,21 @@ remote source text uses `external_untrusted`. Preserve the `trust` and
## Compatibility and features

The binding enables PyO3's `abi3-py311` stable ABI, targeting GIL-enabled
CPython 3.11 and newer. The active PyPI distribution qualification targets
CPython 3.11 through 3.15 on each supported platform; only candidates that pass
the exact 25-cell workflow matrix qualify. Linux wheels use the manylinux2014
baseline; native targets are Linux x86_64 and aarch64, macOS x86_64 and arm64,
and Windows x86_64. CI builds on each target and installs each exact wheel on
all five interpreters without installing Rust in the consumer job. These
claims remain conditional on the corresponding exact-candidate jobs passing.

PyPy, free-threaded CPython, and Windows ARM64 are not claimed. ARMv7 is
planned as experimental SBC support only after its separate build and emulated
installed-wheel qualification passes. The release candidate uses a pinned
manylinux cross toolchain and targets the `manylinux_2_28_armv7l` compatibility
tag; its glibc floor and hard-float ABI must pass artifact audit and emulated
installation before publication. That support is limited to ARMv7 hard-float
Linux with glibc 2.28 or newer. ARMv6, soft-float, Windows ARM64, and Alpine or
other musl systems are not included. After the first release appears on PyPI,
SBC users must require a wheel so pip fails on an unsupported target instead
of trying to compile from source:
CPython 3.11 and newer. Version 0.4.4 passed the exact 25-cell CPython
3.11–3.15 workflow matrix and public binary-only consumer installs. Linux wheels
use the manylinux2014 baseline; native targets are Linux x86_64 and aarch64,
macOS x86_64 and arm64, and Windows x86_64. CI builds on each target and
installs each exact wheel on all five interpreters without source builds in the
consumer job. The exact candidate and public-consumer evidence is recorded in
the M003 closure.

PyPy, free-threaded CPython, and Windows ARM64 are not claimed. ARMv7 support is
experimental SBC support, qualified by a `manylinux_2_28_armv7l` hard-float
wheel, an ELF audit, and emulated public installation. It supports ARMv7
hard-float Linux with glibc 2.28 or newer; physical board compatibility and
performance remain unmeasured. ARMv6, soft-float, Windows ARM64, and Alpine or
other musl systems are not included. SBC users must require a wheel so pip fails
on an unsupported target instead of trying to compile from source:

```bash
python -m pip install --only-binary=:all: eggsearch
Expand All @@ -157,9 +164,8 @@ An sdist build requires Rust 1.89, a C toolchain, and the Cargo dependencies in
`bindings/python/Cargo.lock`. It can build offline when those locked crate
sources are already in Cargo's local cache; a fresh build must be able to fetch
them from Cargo registries. Native wheels avoid those build requirements at
install and runtime. After the M003 first publication is verified, upgrade
with `python -m pip install --upgrade eggsearch` and remove with
`python -m pip uninstall eggsearch`.
install and runtime. Upgrade with `python -m pip install --upgrade eggsearch`
and remove with `python -m pip uninstall eggsearch`.

## Post-publication SBC benchmark

Expand All @@ -168,12 +174,13 @@ the exact public wheel with `--only-binary=:all:`, then run the standard-library
harness outside the repository checkout:

```bash
python -m pip install --only-binary=:all: --report install-report.json eggsearch==VERSION
python -m pip download --only-binary=:all: --no-deps --dest wheelhouse eggsearch==VERSION
python -m pip download --only-binary=:all: --no-deps --dest wheelhouse eggsearch==0.4.4
python -m pip install --only-binary=:all: --no-deps --report install-report.json eggsearch==0.4.4
python /path/to/eggsearch/bindings/python/scripts/smoke_installed_wheel.py
python /path/to/eggsearch/bindings/python/benchmarks/sbc_runtime.py \
--version VERSION --wheel /path/to/wheelhouse/eggsearch-*.whl \
--pip-report install-report.json
--version 0.4.4 --source-sha 1135608af5d625cd72db6704adf3bcabd1a58ab1 \
--wheel /path/to/wheelhouse/eggsearch-0.4.4-*.whl \
--pip-report install-report.json --output sbc-runtime.json
```

The harness verifies that the wheel matches the public PyPI URL and SHA-256 in
Expand Down
23 changes: 15 additions & 8 deletions docs/release-checklist.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,11 +28,18 @@ Short operational checklist. The authoritative release process lives in
- [ ] Review binary checksums and publish the draft release manually
- [ ] Verify the published release has exactly 19 assets (7 executables, 7 `.sha256` sidecars, `install.sh`, `install.ps1`, `release-manifest.json`, `install-exact.sh`, `install-exact.ps1`) and run external Unix/Windows installer smoke

## Separate Python package publication

- [ ] Confirm M001 and M002 exact-SHA qualification and root CI are green
- [ ] Configure PyPI Trusted Publishing for `eggstack/eggsearch`, workflow `release-python-pypi.yml`, environment `pypi`
- [ ] Create GitHub environment `pypi` before dispatching
- [ ] Dispatch the Python publication workflow with the qualified SHA, Python qualification run ID, and synchronized version
- [ ] Confirm public binary-only installs and the M003 closure record before announcing availability
- [ ] Schedule M004 benchmarks on native SBC devices after publication
## Initial Python package publication — completed 2026-10-28

- [x] Confirm M001 and M002 exact-SHA qualification and root CI are green for `1135608af5d625cd72db6704adf3bcabd1a58ab1`
- [x] Configure PyPI Trusted Publishing for `eggstack/eggsearch`, workflow `release-python-pypi.yml`, environment `pypi`
- [x] Create GitHub environment `pypi` before dispatching; no required reviewer was configured per maintainer direction
- [x] Dispatch run `40742653291` with the qualified SHA, Python qualification run `40729011504`, and version `0.4.4`
- [x] Confirm public binary-only installs on five native platforms and emulated ARMv7; see `plans/closure/python-pypi-distribution/003-status.md`
- [ ] Run M004 benchmarks on native aarch64 and ARMv7 SBC devices after publication

## Future Python package publications

- [ ] Qualify the exact candidate source and verify a synchronized, unused Python version
- [ ] Confirm PyPI Trusted Publishing and the pre-created GitHub `pypi` environment remain configured
- [ ] Dispatch `.github/workflows/release-python-pypi.yml` with the exact SHA, successful qualification run ID, and version
- [ ] Confirm public binary-only installs and record the release evidence before announcing availability
38 changes: 20 additions & 18 deletions docs/release.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,24 +62,26 @@ producer contract.
The native Python distribution has its own release path and does not use root
Rust tags, crates.io publication, Eggpack, or the 19-asset binary inventory.
The controlling workstream is `plans/subsystems/python-pypi-distribution-roadmap.md`.
Its first publication must use the exact candidate SHA whose five-platform,
25-cell interpreter matrix, ARMv7 emulated install, source rebuild, audits, and
root CI all passed.

Before dispatching `.github/workflows/release-python-pypi.yml`, configure the
PyPI Trusted Publisher for owner `eggstack`, repository `eggsearch`, workflow
`release-python-pypi.yml`, and pre-create the GitHub environment `pypi`. The
publisher workflow requires the exact candidate SHA, successful Python
qualification run ID, and synchronized package version. Its preflight verifies
the environment exists, then verifies the source and six-wheel plus sdist
inventory before the OIDC publish job. Dispatching the workflow is the explicit
publication action. The publication is complete only after independent public
binary-only installs pass on Linux x86_64/aarch64, macOS x86_64/arm64, Windows
x86_64, and emulated ARMv7.

Do not announce PyPI availability or update the public installation claim
until that post-publication verification and M003 closure record are complete.
Physical SBC measurements belong to M004 and happen after the initial release.
The first publication completed on 2026-10-28 as `eggsearch==0.4.4` from
qualified source `1135608af5d625cd72db6704adf3bcabd1a58ab1`. Publication run
`40742653291` verified the exact source and wheelhouse, published through
Trusted Publishing, and passed public binary-only installs on five native
platform families plus emulated ARMv7. See
`plans/closure/python-pypi-distribution/003-status.md` for the inventory and
evidence.

For future Python releases, configure the PyPI Trusted Publisher for owner
`eggstack`, repository `eggsearch`, workflow `release-python-pypi.yml`, and
pre-create the GitHub environment `pypi`. The workflow takes the exact candidate
SHA, successful Python qualification run ID, and synchronized package version.
It verifies the environment exists, checks the qualified source and artifact
inventory, then publishes with OIDC. Explicit workflow dispatch is the release
action; a required environment reviewer is not configured.

Public install instructions are in `README.md` and `docs/python-library.md`.
ARMv7 support remains experimental until M004 provides physical-board evidence.
Physical SBC measurements happen after publication and do not block a future
Python release unless they reveal a compatibility defect.

## Publication and binary release

Expand Down
Loading
Loading