The Python library is an additive native consumer of the ten existing tool
operations. Its ownership boundary is registered in
plans/adrs/ADR-0005-python-native-library-boundary.md and sequenced by
plans/subsystems/python-native-library-roadmap.md.
Current handoff: M001's shared Rust facade and ten-operation parity are
closed at plans/closure/python-native-library/001-status.md; M002's native
asyncio bridge is closed at plans/closure/python-native-library/002-status.md;
M003's Python API, types, examples, and semantic parity work is closed at
plans/closure/python-native-library/003-status.md; M005 in-flight
cancellation and default-config corrective is closed at
plans/closure/python-native-library/005-status.md; M004 distribution
qualification, M006 exact-SHA closure, and the M007 Windows safe-read
corrective are closed together at plans/closure/python-native-library/004-status.md
(candidate faa1da2, qualifying run 38617598636, before the separate PyPI
publication workstream),
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 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. The published aarch64 wheel passed native device smoke and
benchmarking on a Libre Computer AML-S905X-CC. No device-local source build or
native SBC benchmark was a first-release prerequisite; the ARMv7 wheel remains
experimental because physical 32-bit board evidence is deferred. See
plans/closure/python-pypi-distribution/004-status.md.
src/sdk.rs owns the narrow EggsearchClient, canonical ToolName mapping,
shared ServerState lifetime, and structured SdkError conversion. It
delegates every operation to the matching function under src/mcp/tools/.
Those handlers remain the only owner of argument semantics, provider and
fetch policy, sanitization, evidence identity, warnings, and result shape.
The facade returns tool JSON payloads without MCP envelopes. Cloned clients
share one state; the caller supplies the Tokio runtime.
The facade does not make the rest of the crate's module tree a stable general
Rust library. It introduces no Python dependency, runtime, process, listener,
or background task into the root crate. ToolName stays aligned with the
code-derived tool_contract::ALL_CONTRACTS inventory.
The Python package lives in an independent bindings/python Cargo package.
PyO3 and Python packaging dependencies must not enter the root crate's
default dependency graph or change its binary artifact inventory. Python
import is side-effect-free. The binding owns Python types and lifecycle
adaptation; all execution delegates through src/sdk.rs. The PyO3 layer
initializes one process-scoped Tokio runtime on first operation, caps shared
in-flight calls at 32, and bounds JSON conversion to 1 MiB, 64 levels, and
10,000 values. aclose() rejects new work, cancels active operations, and
waits for their Rust futures to drop; Python task cancellation drops its
corresponding future. The runtime intentionally remains process-scoped.
AsyncEggsearch() preserves no-arg AppConfig::default() semantics.
AsyncEggsearch.from_default_config() and default_config_path() use
Rust-owned eggsearch::core::config::default_config_path() plus
AppConfig::load, preserving explicit-path behavior and CLI missing-file
fallback without reimplementing platform selection in Python. Cancellation
after a started barrier is proven by a src/sdk.rs counted blocking engine
plus a debug-only bridge gate (_test_blocking_execute, _test_gate_state,
_test_gate_reset, _test_gate_release, _test_active_count) that shares the
production ActiveCall, 32-permit, and close-token path; the gate is compiled
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. Python
publication is separate from Rust crate and Eggpack binary releases and uses
the manually dispatched OIDC workflow.
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 has an experimental manylinux_2_28_armv7l
hard-float wheel with emulated public installation; native ARMv7 32-bit
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
and response TypedDict definitions live in bindings/python/python/eggsearch/types.py;
they describe common JSON fields while runtime dictionaries retain additive
keys. The py.typed marker and native extension stub make the package
discoverable to type checkers. tool_names() comes from the Rust SDK's
code-derived canonical inventory. tool_contracts() returns input/output
schemas and the MCP contract fingerprint from the existing server definitions;
the Python test suite checks request type coverage against advertised schema
properties.