mst-python 0.5.0__cp311-cp311-macosx_26_0_universal2.whl

mst/__init__.py

@@ -0,0 +1,68 @@
+"""mst: CGO Python bindings for mst (Meta-Search Tool).
+
+Concurrent multi-engine web search with RRF ranking, zero subprocess overhead.
+
+Usage:
+    import mst
+
+    result = mst.search("rust async runtime comparison")
+    for item in result["results"]:
+        print(f"{item['rank']}. {item['title']}")
+
+    engines = mst.list_engines()
+"""
+
+import asyncio
+
+from ._mst import MSTError, list_engines, search
+
+__all__ = ["search", "search_async", "list_engines", "MSTError"]
+
+
+async def search_async(
+    query: str,
+    engines=None,
+    limit: int = 10,
+    offset: int = 0,
+    rrf_k: int = 60,
+    timeout: str = "8s",
+    weights=None,
+) -> dict:
+    """Async wrapper around :func:`search`.
+
+    The native CGO call is blocking (the Go runtime releases the GIL while it
+    runs), so this thin wrapper offloads it to the event loop's default executor
+    via :func:`asyncio.to_thread`. It returns the same envelope and raises the
+    same :class:`MSTError` as :func:`search`.
+
+    This is intentionally *not* a second search implementation: every argument
+    is forwarded unchanged.
+    """
+    return await asyncio.to_thread(
+        search,
+        query,
+        engines=engines,
+        limit=limit,
+        offset=offset,
+        rrf_k=rrf_k,
+        timeout=timeout,
+        weights=weights,
+    )
+
+# Reflect the installed distribution version (populated by setup.py from the
+# release tag). Falls back when run from a source tree that isn't installed.
+try:
+    from importlib.metadata import PackageNotFoundError, version as _dist_version
+
+    # The PyPI distribution is `mst-python` while the import package is `mst`;
+    # accept either name so editable/source installs and wheels both work.
+    for _dist in ("mst-python", "mst"):
+        try:
+            __version__ = _dist_version(_dist)
+            break
+        except PackageNotFoundError:
+            continue
+    else:
+        __version__ = "0.0.0-dev"
+except ImportError:  # Python <3.8 (unsupported, but stay safe)
+    __version__ = "0.0.0-dev"

mst_python-0.5.0.dist-info/METADATA

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: mst-python
+Version: 0.5.0
+Summary: CGO Python bindings for mst (Meta-Search Tool) — concurrent multi-engine web search with RRF ranking
+Author: mst contributors
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# mst-python — Meta Search Tool (Python bindings)
+
+[![Release](https://github.com/openmtx/meta-search-tool/actions/workflows/release.yml/badge.svg)](https://github.com/openmtx/meta-search-tool/actions/workflows/release.yml)
+[![PyPI](https://img.shields.io/pypi/v/mst-python)](https://pypi.org/project/mst-python/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/mst-python)](https://pypi.org/project/mst-python/)
+
+CGO Python bindings for **mst** — a concurrent multi-engine web search tool with
+transparent RRF ranking. Fan out to 12+ engines in parallel, get merged JSON
+results with scores. No server, no setup.
+
+```python
+import mst
+
+# Search across all enabled engines
+result = mst.search("rust async runtime comparison")
+
+# Or pick specific engines
+result = mst.search("riscv paging", engines=["ddg", "google"], limit=10)
+
+print(f"Found {len(result['results'])} results in {result['took_ms']}ms")
+for r in result['results']:
+    print(f"  #{r['rank']}  {r['title']}  (score={r['score']})")
+```
+
+## Features
+
+- **14 engines** across general web, academic, reference, Q&A, and AI categories
+- **Concurrent fan-out** with per-engine timeouts — a slow engine never blocks the run
+- **RRF ranking** with configurable per-engine weights and smoothing constant
+- **Keyless engines** work out of the box: DuckDuckGo, Google, Wikipedia, arXiv, Europe PMC, and more
+- **Keyed engines** (Brave, Bing, Tavily, Jina) ready when you set their API keys
+- **Async API** (`search_async`) for asyncio consumers; the native call releases the GIL
+
+## Installation
+
+```bash
+pip install mst-python
+```
+
+Works on Linux (manylinux_2_34 x86_64) and macOS (Apple Silicon arm64).
+
+## Quick start
+
+```python
+import mst
+
+# List all engines and their status
+engines = mst.list_engines()
+for e in engines:
+    print(f"{e['name']:20s}  {e['status']:15s}  weight={e['weight']}")
+
+# Run a search
+result = mst.search("python asyncio vs threading", limit=5)
+print(result)
+```
+
+## API
+
+### `mst.search(query, engines=None, limit=10, offset=0, rrf_k=60, timeout="8s", weights=None)`
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `query` | `str` | — | Search query |
+| `engines` | `list[str]` or `None` | `None` | Engine whitelist (`None` = all enabled engines) |
+| `limit` | `int` | `10` | Max merged results (1–100) |
+| `offset` | `int` | `0` | Skip first N results |
+| `rrf_k` | `int` | `60` | RRF smoothing constant |
+| `timeout` | `str` | `"8s"` | Per-engine timeout duration |
+| `weights` | `dict[str, float]` or `None` | `None` | Per-engine weight overrides |
+
+Returns a dict with `query`, `took_ms`, `results` (list of ranked results).
+
+### `await mst.search_async(...)`
+
+Async wrapper around `mst.search()` with the same arguments, return value, and
+`MSTError` behavior. It is **additive**: existing consumers that call
+`asyncio.to_thread(mst.search, ...)` keep working and can adopt the wrapper
+later without a breaking change. It forwards the blocking native call to
+`asyncio.to_thread`, so the event loop keeps running during a search. The native
+CGO library releases the GIL, so concurrent `search_async()` calls overlap
+instead of serializing.
+
+```python
+import asyncio
+import mst
+
+async def main():
+    results = await asyncio.gather(
+        mst.search_async("rust async", limit=5),
+        mst.search_async("python asyncio", limit=5),
+        mst.search_async("go concurrency", limit=5),
+    )
+    for result in results:
+        print(result["query"], len(result["results"]))
+
+asyncio.run(main())
+```
+
+Cancellation note: `asyncio.wait_for(asyncio.shield(...))` and task cancellation
+stop the *await*, not the native call. The `timeout` argument bounds the Go-side
+search; a cancelled worker may finish in the background, and subsequent calls
+are unaffected.
+
+### `mst.list_engines()`
+
+Returns a list of engine dicts with `name`, `enabled`, `keyed`, `weight`, `category`, `status`.
+
+### `mst.__version__`
+
+Package version string (derived from the release tag when installed via PyPI).
+
+## Requirements
+
+- Python ≥ 3.11
+- Linux (x86_64, glibc ≥ 2.34) or macOS (arm64)
+
+No runtime dependencies — the CGO shared library is bundled in the wheel.
+
+## License
+
+Apache-2.0. See [`LICENSE`](https://github.com/openmtx/meta-search-tool/blob/master/LICENSE).

mst_python-0.5.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+mst/__init__.py,sha256=4MfzqZrtwPVQ_HelYZZtRKOMEZAH2CKB9knJhY-L30w,2018
+mst/_mst.cpython-311-darwin.so,sha256=TIN5FQtf4L93mToIvSO5xkwl9U_-qd5-3b5gBz_0_gY,242488
+mst/_mst.so,sha256=tgYbTzOWImAb4wLE3foaZYYd-DUp2N2fVtn5h2aC7UU,8112162
+mst_python-0.5.0.dist-info/METADATA,sha256=7CWAWi-5VaxLhA4Q_NwLLIKYkrL978jVuV2lOLA4ons,4876
+mst_python-0.5.0.dist-info/WHEEL,sha256=_qm6y1zAa80MnyE0XHj_erdX4-_--_YglqQ_pu58BjM,114
+mst_python-0.5.0.dist-info/top_level.txt,sha256=wWnObFIH0CbsgenDXlDpKZv1zdBkbCM4iASswi0Vofw,4
+mst_python-0.5.0.dist-info/RECORD,,

mst_python-0.5.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: false
+Tag: cp311-cp311-macosx_26_0_universal2
+

mst_python-0.5.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mst