feat(python+docs): add sparrow_engine.__version__ + fix README install lines for uv venv

Two doc/API gaps surfaced during a 2026-05-26 prod-PyPI manual smoke
attempt in a fresh uv venv:

1. README pip install lines fail under `uv venv`. `uv venv` does not
   install pip in the venv, so `source activate && pip install ...`
   falls back to the system pip — which usually targets the wrong
   Python version and errors with "No matching distribution found"
   for the cp311-abi3 wheel. Show both `uv pip install` (uv venv) and
   `pip install` (stdlib venv) install flows; spell out the cp311
   abi3 floor.

2. `sparrow_engine.__version__` missing. The conventional Python
   handle for "which version did I install" raised AttributeError;
   the only knob was `importlib.metadata.version('sparrow-engine-gpu')`
   which required the tester to know the distribution name. Single-
   source the version from wheel METADATA via
   `importlib.metadata.version(...)`; resolve the GPU dist name first,
   fall through to the CPU name, then `"unknown"` on broken install.

Changes:
- README.md §Python package only (PyPI): split into "With uv" and
  "With stdlib venv" subsections; add cp311 abi3 floor note + explain
  why bare `pip install` after `uv venv` fails; add the
  __version__ smoke command as the post-install sanity check.
- sparrow-engine-python/python/sparrow_engine/__init__.py: add
  _resolve_version() at the top, set module-level __version__, append
  to __all__.
- sparrow-engine-python/tests/test_version_attr.py: 3 new tests
  asserting the attribute exists, is in __all__, and matches PEP-440
  (or the "unknown" fallback). All 3 pass; full suite 17 pass 8 skip.
- docs/user-manual.md §6.1: document __version__ as a public attribute
  next to the 15-function table; cite the resolver at __init__.py:16-29.

Verified end-to-end on the dev box: built sparrow_engine-0.1.4 wheel
locally, installed into a fresh `uv venv --python 3.11`, ran
`python -c "import sparrow_engine; print(sparrow_engine.__version__)"`
→ `0.1.4`, and confirmed `'__version__' in sparrow_engine.__all__`.

This change does NOT bump pyproject.toml from 0.1.4 to 0.1.5. The fixes
land in source for the next release; the prod-PyPI 0.1.4 wheel still
lacks __version__ until a 0.1.5 publish.

Origin: user `/session-init sparrow-engine` 2026-05-26 PT, prod-PyPI
smoke attempt in a fresh uv venv surfaced both gaps.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: zhmiao

README.md

@@ -29,9 +29,34 @@ and **cuDNN ≥9.10** (cuDNN 9.8 has a Conv-engine bug on sm_89).
 ### Python package only (PyPI)
 
 If you only want the Python wheel — no CLI, no Docker image — install
-straight from PyPI:
+straight from PyPI. Both wheels target CPython ≥ 3.11 (`cp311-abi3`), so
+make sure your venv runs Python 3.11 or newer.
+
+**With `uv` (recommended)**:
 
 ```bash
+uv venv --python 3.11
+source .venv/bin/activate         # Windows: .venv\Scripts\activate
+
+# CPU
+uv pip install sparrow-engine
+
+# GPU (Linux x86_64 only; requires CUDA 12.6 runtime on the host)
+uv pip install sparrow-engine-gpu
+```
+
+`uv venv` does not ship `pip` inside the venv by default, so use `uv pip
+install` (uv's pip-compatible wrapper) instead of bare `pip install`.
+Calling `pip install …` after `source activate` falls back to the system
+pip, which usually targets the wrong Python version and fails with
+`No matching distribution found`.
+
+**With stdlib `venv`**:
+
+```bash
+python3.11 -m venv .venv
+source .venv/bin/activate         # Windows: .venv\Scripts\activate
+
 # CPU
 pip install sparrow-engine
 
@@ -40,7 +65,9 @@ pip install sparrow-engine-gpu
 ```
 
 Both wheels import as `sparrow_engine`. Never install both into the same
-environment. See [§6 of the user manual](docs/user-manual.md#6-python-package--sparrow-engine)
+environment. Check the installed version with
+`python -c "import sparrow_engine; print(sparrow_engine.__version__)"`.
+See [§6 of the user manual](docs/user-manual.md#6-python-package--sparrow-engine)
 for the full API surface and GPU sidecar options.
 
 ---

docs/user-manual.md

@@ -717,7 +717,9 @@ $ spe pipeline IMG.jpg \
 | `visualize_audio(results, output_dir, ...)` | None; writes mel-spectrogram PNGs with detection windows for `detect_audio` results. |
 | `export(results, format, output)` | None; writes consolidated batch output |
 
-**Cite**: `sparrow-engine/sparrow-engine-python/python/sparrow_engine/__init__.py:212-246` (`__all__`); per-function defs in the same file.
+Plus one public attribute: `sparrow_engine.__version__` (`str`) — the installed wheel's version, single-sourced from PyPI metadata via `importlib.metadata.version(...)`. Resolves the GPU distribution name first, then the CPU name, then falls back to `"unknown"` on a broken install. Lets a tester confirm the wheel they just installed without grepping `pip show`.
+
+**Cite**: `sparrow-engine/sparrow-engine-python/python/sparrow_engine/__init__.py:212-247` (`__all__`); per-function defs in the same file; `__version__` resolver at `__init__.py:16-29`.
 
 ---
 

sparrow-engine/sparrow-engine-python/python/sparrow_engine/__init__.py

@@ -4,9 +4,29 @@
 import os
 import sys
 import threading
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
 from pathlib import Path
 from typing import Callable, Optional, Union
 
+
+# Public package version. Single-sourced from the wheel METADATA (which
+# itself comes from sparrow-engine-python/pyproject.toml). Tries the GPU
+# distribution name first because the GPU wheel is the more specific
+# install — if both were ever resolvable in the same env (Provides-Dist
+# advisory only; not a hard guard per Phase 3.8 Phase C `feedback_no_soft_tolerance_framing_on_gates.md`),
+# preferring GPU is the safer reflection of what's actually loaded.
+def _resolve_version() -> str:
+    for dist in ("sparrow-engine-gpu", "sparrow-engine"):
+        try:
+            return _pkg_version(dist)
+        except PackageNotFoundError:
+            continue
+    return "unknown"
+
+
+__version__ = _resolve_version()
+
+
 # S6: per-file progress callback. Invoked once per input file, AFTER the
 # file's inference attempt resolves (success or failure), with
 # ``(index, total, filename)`` positional args. ``index`` is 0-based.
@@ -210,6 +230,8 @@ def _configure_ort_dylib_path() -> None:
 from sparrow_engine._sparrow_engine_core import visualize_audio as _visualize_audio_core
 
 __all__ = [
+    # Version (single-sourced from wheel METADATA via importlib.metadata)
+    "__version__",
     # Functions
     "init",
     "detect",

sparrow-engine/sparrow-engine-python/tests/test_version_attr.py

@@ -0,0 +1,51 @@
+"""Tests for the public `sparrow_engine.__version__` attribute.
+
+`__version__` is single-sourced from the wheel METADATA via
+`importlib.metadata.version(...)`, which itself comes from
+`sparrow-engine-python/pyproject.toml`. The CPU wheel installs as
+`sparrow-engine`; the GPU wheel installs as `sparrow-engine-gpu`. Both
+import as `sparrow_engine`, so the resolver tries the GPU dist name first
+and falls through to the CPU dist name.
+
+This test asserts the public API contract, not the version string itself
+(which changes every release). A failure here means a tester's
+`python -c "import sparrow_engine; print(sparrow_engine.__version__)"`
+will break, which was the gap surfaced by the 2026-05-26 prod-PyPI smoke
+attempt.
+"""
+from __future__ import annotations
+
+import re
+
+import sparrow_engine
+
+
+def test_version_attribute_exists() -> None:
+    """`sparrow_engine.__version__` must be a non-empty string."""
+    assert hasattr(sparrow_engine, "__version__"), (
+        "sparrow_engine.__version__ is missing — see "
+        "sparrow-engine-python/python/sparrow_engine/__init__.py"
+    )
+    assert isinstance(sparrow_engine.__version__, str)
+    assert sparrow_engine.__version__, "version string is empty"
+
+
+def test_version_listed_in__all__() -> None:
+    """`__version__` must be in `__all__` so `from sparrow_engine import *` exports it."""
+    assert "__version__" in sparrow_engine.__all__
+
+
+def test_version_shape_is_pep440_or_unknown() -> None:
+    """Version must be either a PEP-440-shaped string or the fallback `"unknown"`.
+
+    PEP-440 covers all current and foreseeable shapes: `0.1.4`, `0.1.4rc1`,
+    `0.1.4.dev3+gabc1234`, etc. The fallback `"unknown"` should only fire
+    when neither distribution name is resolvable, which would mean
+    `pip install` somehow landed the package without metadata — a broken
+    install state we still want to handle gracefully rather than crash.
+    """
+    v = sparrow_engine.__version__
+    if v == "unknown":
+        return
+    # Minimal PEP-440 sniff: starts with a digit, contains only [0-9a-z.+-]
+    assert re.match(r"^[0-9][0-9a-z.+\-]*$", v), f"unexpected version shape: {v!r}"