Skip to content

Latest commit

 

History

History
101 lines (88 loc) · 5.94 KB

python-library.md

File metadata and controls

101 lines (88 loc) · 5.94 KB

Python Native Library

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.

Rust operation facade

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.

Python binding and distribution boundary

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.