openrunner-sdk 2.41.3__tar.gz → 2.41.5__tar.gz

{openrunner_sdk-2.41.3 → openrunner_sdk-2.41.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openrunner-sdk
-Version: 2.41.3
+Version: 2.41.5
 Summary: OpenRunner SDK - W&B-compatible ML experiment tracking client
 Project-URL: Homepage, https://github.com/jqueguiner/openrunner
 Project-URL: Repository, https://github.com/jqueguiner/openrunner

{openrunner_sdk-2.41.3 → openrunner_sdk-2.41.5}/openrunner/CLAUDE.md

@@ -84,6 +84,32 @@ CLI: `openrunner datasets index org/name --text-col en --text-col fr`,
 combined `_text` column so one query spans all text fields; preview/search read
 the LanceDB table on the dataset's own connection.
 
+### Search modes + query-derived datasets
+
+Beyond FTS, the client exposes semantic / lexical search and **derivation by
+query** — build a child dataset from a SUBSET of a parent selected by a search
+(only matching primary keys stored; no media copied; de-dup + lineage automatic).
+These delegate to the native Rust core (`openrunner-core` wheel) when installed,
+falling back to pure-Python httpx otherwise:
+
+```python
+ord.search_dataset(repo, q, mode="mixed"|"exact", lang="fr")   # BM25 / phrase, lang filter
+ord.optimize_embedding_search(repo)                            # build ANN index (once)
+ord.semantic_search(repo, q, lang="en,fr")                     # vector (cosine) search
+ord.word_lookup(repo, "medical,doctor", op="union"|"intersect", lang="fr")  # lexical_map
+ord.keyword_expand("medical terms in french", count=300)       # LLM -> {keywords, csv, count}
+
+# derive: mode = word (op union/intersect) | fts | exact | semantic; lang filter; append via target_repo_id
+child = ord.derive_by_query(parent, keywords_csv, name="org/medical-fr",
+                            mode="word", lang="fr", limit=5000)
+ord.derive_by_query(parent, "more,terms", target_repo_id="org/medical-fr", mode="word")  # append, de-dup
+ord.derived_rows("org/medical-fr", limit=50)                   # member keys + inherited parent fields
+```
+
+`word`+`op="union"` = rows matching ANY term; `op="intersect"` (via `word_lookup`)
+= rows matching ALL. `semantic` needs `optimize_embedding_search` first. Slash
+command: `/openrunner:derive-dataset` (query-derivation **or** computed-column).
+
 # OpenRunner MCP Integration
 
 When the user publishes a MODEL, or asks to write/update a model card:

{openrunner_sdk-2.41.3 → openrunner_sdk-2.41.5}/openrunner/__init__.py

@@ -101,8 +101,14 @@ from openrunner.datasets import (
     link_project,
     load_dataset,
     add_derivation,
+    derive_by_query,
+    derived_rows,
+    keyword_expand,
+    optimize_embedding_search,
     push_dataset,
     search_dataset,
+    semantic_search,
+    word_lookup,
     set_dataset_card,
     set_storage_policy,
     upload_file,
@@ -181,7 +187,7 @@ launch.from_run = _launch_from_run  # type: ignore[attr-defined]
 # openrunner.trace.patch_openai() syntax
 trace.patch_openai = _patch_openai  # type: ignore[attr-defined]
 
-__version__ = "2.41.3"
+__version__ = "2.41.4"
 
 logger = logging.getLogger("openrunner")
 

{openrunner_sdk-2.41.3 → openrunner_sdk-2.41.5}/openrunner/_native.py

@@ -9,7 +9,10 @@ single-implementation point, never a hard dependency.
 
 Covered surface today: projects (incl. linked repo), artifacts/versions,
 presigned downloads (selective, GIL released during transfers), container
-registries + broker login tokens.
+registries + broker login tokens, dataset editable-overlay columns
+(add column / set cell / edit row / get row — source columns stay read-only),
+and dataset search + query-derivation (full-text / semantic / word union·intersect,
+LLM keyword-expand, derive-by-query + derived rows).
 """
 
 from __future__ import annotations

{openrunner_sdk-2.41.3 → openrunner_sdk-2.41.5}/openrunner/datasets.py

@@ -194,14 +194,27 @@ class DatasetsClient:
                or _g.get("base_url") or "http://localhost:8000")
         if not key:
             raise ValueError("API key required. Set OPENRUNNER_API_KEY, pass api_key=, or run `openrunner login`.")
+        # Raw creds kept so the optional native core (Rust) can be built lazily —
+        # the crate appends its own /api/v1, so hand it the bare base URL.
+        self._base_url = url.rstrip("/")
+        self._api_key = key
+        self._native: Any = "unset"  # sentinel: native core not yet resolved
         from ._retry_transport import RetryTransport
         self._http = httpx.Client(
-            base_url=f"{url.rstrip('/')}/api/v1",
-            headers={"Authorization": f"Bearer {key}"},
+            base_url=f"{self._base_url}/api/v1",
+            headers={"Authorization": f"Bearer {self._api_key}"},
             timeout=timeout,
             transport=RetryTransport(),
         )
 
+    def _native_client(self):
+        """The native (Rust/PyO3) client if the ``openrunner-core`` wheel is
+        installed, else ``None`` — an accelerator with a pure-Python fallback."""
+        if self._native == "unset":
+            from openrunner import _native
+            self._native = _native.native_client(self._base_url, self._api_key)
+        return self._native
+
     # -- resolution ----------------------------------------------------------
     def _org_id(self, org: str) -> str:
         r = self._http.get("/organizations")
@@ -733,13 +746,168 @@ class DatasetsClient:
         _check(r)
         return r.json()
 
-    def search_dataset(self, repo_id: str, query: str, *, limit: int = 20) -> list[dict]:
-        """Full-text search a dataset's index. Call ``index_dataset`` first."""
+    def search_dataset(
+        self,
+        repo_id: str,
+        query: str,
+        *,
+        limit: int = 20,
+        mode: str = "mixed",
+        lang: str = "",
+    ) -> list[dict]:
+        """Full-text search a dataset's index. Call ``index_dataset`` first.
+
+        ``mode``: "mixed" (ranked tokens, default) or "exact" (phrase match).
+        ``lang``: restrict to a language / CSV ("fr" or "fr,en"); "" = all.
+        Delegates to the native (Rust) core when the ``openrunner-core`` wheel is
+        installed, else pure-Python httpx.
+        """
         ds = self._resolve(repo_id)
-        r = self._http.get(f"/datasets/{ds.id}/search", params={"q": query, "limit": limit})
+        nat = self._native_client()
+        if nat is not None:
+            return nat.dataset_search(str(ds.id), query, mode, lang, limit).get("rows", [])
+        params: dict[str, Any] = {"q": query, "limit": limit, "mode": mode}
+        if lang:
+            params["lang"] = lang
+        r = self._http.get(f"/datasets/{ds.id}/search", params=params)
         _check(r)
         return r.json().get("rows", [])
 
+    # -- semantic / lexical / query-derivation -------------------------------
+    def semantic_search(
+        self, repo_id: str, query: str, *, limit: int = 20, lang: str = ""
+    ) -> list[dict]:
+        """Vector (cosine ANN) search over a dataset's embeddings.
+
+        Requires the embedding index built first via
+        ``optimize_embedding_search``. Native core when available, else httpx.
+        """
+        ds = self._resolve(repo_id)
+        nat = self._native_client()
+        if nat is not None:
+            out = nat.semantic_search(str(ds.id), query, lang, limit)
+            return out.get("rows", out.get("hits", []))
+        params: dict[str, Any] = {"q": query, "limit": limit}
+        if lang:
+            params["lang"] = lang
+        r = self._http.get(f"/datasets/{ds.id}/semantic", params=params)
+        _check(r)
+        return r.json().get("rows", r.json().get("hits", []))
+
+    def optimize_embedding_search(
+        self,
+        repo_id: str,
+        *,
+        text_column: str | None = None,
+        max_rows: int = 200000,
+        model: str | None = None,
+    ) -> dict:
+        """Embed missing rows and build the ANN index that ``semantic_search``
+        (and derive ``mode="semantic"``) need. Native core when available."""
+        ds = self._resolve(repo_id)
+        nat = self._native_client()
+        if nat is not None:
+            return nat.optimize_embedding_search(str(ds.id), text_column, max_rows, model)
+        body = {"text_column": text_column, "max_rows": max_rows, "model": model}
+        r = self._http.post(
+            f"/datasets/{ds.id}/optimize-embedding-search", json=body, timeout=1800.0
+        )
+        _check(r)
+        return r.json()
+
+    def word_lookup(
+        self, repo_id: str, terms: str | list[str], *, op: str = "union", lang: str = ""
+    ) -> dict:
+        """Word(s) -> matching-row lookup via the ``lexical_map`` table.
+
+        ``terms`` is one word, a CSV string, or a list. ``op`` combines
+        multi-term hits: "union" (ANY) or "intersect" (ALL). ``lang`` scopes to a
+        language / CSV. Returns per-term df + combined ids. Native core when
+        available, else httpx.
+        """
+        ds = self._resolve(repo_id)
+        term = ",".join(terms) if isinstance(terms, (list, tuple)) else terms
+        nat = self._native_client()
+        if nat is not None:
+            return nat.word_lookup(str(ds.id), term, op, lang)
+        params: dict[str, Any] = {"term": term, "op": op}
+        if lang:
+            params["lang"] = lang
+        r = self._http.get(f"/datasets/{ds.id}/word-lookup", params=params)
+        _check(r)
+        return r.json()
+
+    def keyword_expand(
+        self, prompt: str, *, count: int = 500, model: str | None = None
+    ) -> dict:
+        """Expand a domain prompt into many search keywords via an LLM.
+
+        Returns ``{keywords, csv, count, model, prompt}`` — feed ``csv`` into
+        ``word_lookup`` or ``derive_by_query(mode="word", q=csv)``. Native core
+        when available, else httpx.
+        """
+        nat = self._native_client()
+        if nat is not None:
+            return nat.keyword_expand(prompt, count, model)
+        body = {"prompt": prompt, "count": count, "model": model}
+        r = self._http.post("/datasets/keyword-expand", json=body, timeout=120.0)
+        _check(r)
+        return r.json()
+
+    def derive_by_query(
+        self,
+        repo_id: str,
+        q: str,
+        *,
+        name: str | None = None,
+        mode: str = "semantic",
+        lang: str | None = None,
+        limit: int = 2000,
+        target_repo_id: str | None = None,
+        project_id: str | None = None,
+    ) -> DatasetInfo:
+        """Create (or append to) a dataset **derived from a query** over ``repo_id``.
+
+        ``mode``: "word" (``q`` = term / CSV; pairs with LLM ``keyword_expand``),
+        "fts" (BM25), "exact" (phrase), "semantic" (vector — needs
+        ``optimize_embedding_search``). ``lang`` filters by language / CSV. Pass
+        ``name`` to create, or ``target_repo_id`` to append (must derive from the
+        same parent). Lineage is recorded automatically. The query runs and
+        member keys are recorded natively when the core wheel is installed; the
+        parent/target resolution + DatasetInfo wrapping stay in Python.
+        """
+        ds = self._resolve(repo_id)
+        body: dict[str, Any] = {"mode": mode, "q": q, "limit": limit}
+        if name:
+            body["name"] = name
+        if lang:
+            body["lang"] = lang
+        if project_id:
+            body["project_id"] = str(project_id)
+        if target_repo_id:
+            body["target_dataset_id"] = str(self._resolve(target_repo_id).id)
+        elif not name:
+            raise ValueError("derive_by_query needs either name= (create) or target_repo_id= (append)")
+        nat = self._native_client()
+        if nat is not None:
+            return DatasetInfo._from_json(nat.derive_dataset(str(ds.id), body))
+        r = self._http.post(f"/datasets/{ds.id}/derive", json=body, timeout=600.0)
+        _check(r)
+        return DatasetInfo._from_json(r.json())
+
+    def derived_rows(self, repo_id: str, *, limit: int = 50, offset: int = 0) -> dict:
+        """Page a query-derived dataset's rows: member keys + inherited parent
+        fields (lineage-namespaced) + extra columns. Native core when available."""
+        ds = self._resolve(repo_id)
+        nat = self._native_client()
+        if nat is not None:
+            return nat.derived_rows(str(ds.id), limit, offset)
+        r = self._http.get(
+            f"/datasets/{ds.id}/derived-rows", params={"limit": limit, "offset": offset}
+        )
+        _check(r)
+        return r.json()
+
     def update_dataset(self, repo_id: str, **fields: Any) -> DatasetInfo:
         ds = self._resolve(repo_id)
         if "card" in fields:
@@ -812,6 +980,9 @@ class DatasetsClient:
         rejected. Returns the editable column names.
         """
         ds = self._resolve(repo_id)
+        nat = self._native_client()
+        if nat is not None:
+            return nat.add_dataset_column(str(ds.id), name, default)
         r = self._http.post(f"/datasets/{ds.id}/columns",
                             json={"name": name, "default": default})
         _check(r)
@@ -826,6 +997,9 @@ class DatasetsClient:
         ``{ok, debug_id, column}``.
         """
         ds = self._resolve(repo_id)
+        nat = self._native_client()
+        if nat is not None:
+            return nat.set_dataset_cell(str(ds.id), debug_id, column, value)
         r = self._http.patch(f"/datasets/{ds.id}/cell",
                             json={"debug_id": debug_id, "column": column, "value": value})
         _check(r)
@@ -839,6 +1013,9 @@ class DatasetsClient:
         a read-only source column. Returns ``{ok, debug_id, columns}``.
         """
         ds = self._resolve(repo_id)
+        nat = self._native_client()
+        if nat is not None:
+            return nat.edit_dataset_row(str(ds.id), debug_id, values)
         r = self._http.patch(f"/datasets/{ds.id}/rows/{debug_id}", json={"values": values})
         _check(r)
         return r.json()
@@ -849,6 +1026,9 @@ class DatasetsClient:
         ``{debug_id, row, editable_columns}`` (everything in ``row`` not listed in
         ``editable_columns`` is a read-only parent column)."""
         ds = self._resolve(repo_id)
+        nat = self._native_client()
+        if nat is not None:
+            return nat.get_dataset_row(str(ds.id), debug_id)
         r = self._http.get(f"/datasets/{ds.id}/row", params={"debug_id": debug_id})
         _check(r)
         return r.json()
@@ -1107,6 +1287,36 @@ def search_dataset(repo_id: str, query: str, **kwargs: Any) -> list[dict]:
     return _c().search_dataset(repo_id, query, **kwargs)
 
 
+def semantic_search(repo_id: str, query: str, **kwargs: Any) -> list[dict]:
+    """Vector (cosine ANN) search — needs ``optimize_embedding_search`` first."""
+    return _c().semantic_search(repo_id, query, **kwargs)
+
+
+def optimize_embedding_search(repo_id: str, **kwargs: Any) -> dict:
+    """Embed rows + build the ANN index for semantic search / semantic-derive."""
+    return _c().optimize_embedding_search(repo_id, **kwargs)
+
+
+def word_lookup(repo_id: str, terms: "str | list[str]", **kwargs: Any) -> dict:
+    """Word(s) -> rows via lexical_map; ``op`` union|intersect, ``lang`` filter."""
+    return _c().word_lookup(repo_id, terms, **kwargs)
+
+
+def keyword_expand(prompt: str, **kwargs: Any) -> dict:
+    """LLM-expand a domain prompt into search keywords ({keywords, csv, count})."""
+    return _c().keyword_expand(prompt, **kwargs)
+
+
+def derive_by_query(repo_id: str, q: str, **kwargs: Any) -> "DatasetInfo":
+    """Create/append a dataset derived from a word|fts|exact|semantic query."""
+    return _c().derive_by_query(repo_id, q, **kwargs)
+
+
+def derived_rows(repo_id: str, **kwargs: Any) -> dict:
+    """Page a query-derived dataset's rows (member keys + inherited parent fields)."""
+    return _c().derived_rows(repo_id, **kwargs)
+
+
 def set_storage_policy(repo_id: str, tier: str) -> dict:
     return _c().set_storage_policy(repo_id, tier)
 

{openrunner_sdk-2.41.3 → openrunner_sdk-2.41.5}/openrunner/install_commands.py

@@ -2135,14 +2135,54 @@ Give the dataset **URL** (`<base>/datasets/<id>`), the modality/tasks/languages,
 
 DERIVE_DATASET_CMD = """---
 name: {prefix}derive-dataset
-description: Derive a dataset from an existing one by adding a computed column (e.g. a quality/`suspicious` flag) — keeps lineage, never re-uploads the parent's media
-argument-hint: "[parent org/name] [child org/name] [--column NAME]"
+description: Derive a dataset from an existing one — either by a SEARCH QUERY (semantic / word union·intersect / fts / exact, with language filter + LLM keyword expansion) or by adding a computed column. Keeps lineage, never re-uploads the parent's media.
+argument-hint: "[parent org/name] [child org/name] [--query ... | --column NAME]"
 allowed-tools:
   - Bash
   - Read
   - AskUserQuestion
 ---
 
+Two ways to derive a NEW dataset from a parent, both lineage-tracked and media-free:
+
+- **A. Query-derivation** — select a SUBSET of the parent's rows by a search: `semantic`, `word` (term list, UNION or INTERSECT), `fts` (BM25), or `exact` (phrase), with an optional **language filter** and optional **LLM keyword expansion**. Only matching primary keys are stored — no rows/media copied, de-dup automatic. Use when the user says "make a dataset of the medical/french/... clips", "everything matching X", "semantically similar to X".
+- **B. Computed-column** — add one or more computed columns (e.g. a heuristic `suspicious` GT-quality flag) keyed 1:1 to the parent rows.
+
+Pick by intent: **subset/select rows -> A**; **annotate/flag rows -> B**.
+
+---
+
+## A. Query-derivation (semantic / word union·intersect / fts / exact + lang + LLM keywords)
+
+All server-side; the SDK delegates to the native Rust core when installed. `PARENT` must be indexed (`ds.index_dataset(...)`; for `semantic`, also `ds.optimize_embedding_search(...)`).
+
+```bash
+python3 -c "
+from openrunner import datasets as ds
+
+kw = ds.keyword_expand('medical terms in french', count=300)   # {{keywords, csv, count}}
+child = ds.derive_by_query('ORG/PARENT', kw['csv'],
+    name='ORG/medical-fr', mode='word', lang='fr', limit=5000)   # WORD union + lang filter
+print('created', child.name, child.id)
+
+hit = ds.word_lookup('ORG/PARENT', 'medical,doctor,prescription', op='intersect', lang='fr')  # ALL terms
+
+ds.optimize_embedding_search('ORG/PARENT')                       # build ANN index once
+ds.derive_by_query('ORG/PARENT', 'patient describing symptoms',
+    name='ORG/symptom-desc', mode='semantic', lang='en,fr')      # SEMANTIC
+
+ds.derive_by_query('ORG/PARENT', 'insurance claim', name='ORG/claims', mode='fts')   # BM25
+ds.derive_by_query('ORG/PARENT', 'pharmacy,pharmacist', target_repo_id='ORG/medical-fr', mode='word')  # append, de-dup
+print(ds.derived_rows('ORG/medical-fr', limit=10))
+"
+```
+
+Query modes (`mode=`): `word` (CSV of terms; `op='union'|'intersect'`), `fts` (BM25), `exact` (phrase), `semantic` (vector ANN). `lang=` takes a language or CSV ("fr" / "en,fr"); "" = all. Lineage to `PARENT` is recorded automatically by `derive_by_query`.
+
+---
+
+## B. Computed-column derivation
+
 Derive a NEW dataset from an existing parent by adding one or more **computed columns** (e.g. a heuristic `suspicious` GT-quality flag), preserving lineage.
 
 **Datasets are first-class — do NOT use `openrunner.Artifact` for this.** An Artifact is a model/file blob attached to a run; a dataset is a governed, queryable, lineage-tracked entity. Deriving = a child dataset linked to its parent via `add_derivation`, so the platform shows the lineage graph and **blocks deleting the parent while children exist**.

{openrunner_sdk-2.41.3 → openrunner_sdk-2.41.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openrunner-sdk"
-version = "2.41.3"
+version = "2.41.5"
 description = "OpenRunner SDK - W&B-compatible ML experiment tracking client"
 readme = "README.md"
 license = {text = "MIT"}

{openrunner_sdk-2.41.3 → openrunner_sdk-2.41.5}/tests/test_datasets_module.py

@@ -684,11 +684,121 @@ def test_index_dataset_truncated_warns(monkeypatch):
 
 def test_search_dataset(monkeypatch):
     c = _client(monkeypatch)
+    c._native = None  # force httpx fallback (no native wheel)
     c._resolve = MagicMock(return_value=DatasetInfo._from_json(_DS_JSON))
     c._http.get.return_value = _resp(200, {"rows": [{"id": 1}]})
     assert c.search_dataset("gladia/wmt", "hi") == [{"id": 1}]
 
 
+def test_search_dataset_mode_and_lang(monkeypatch):
+    c = _client(monkeypatch)
+    c._native = None
+    c._resolve = MagicMock(return_value=DatasetInfo._from_json(_DS_JSON))
+    c._http.get.return_value = _resp(200, {"rows": []})
+    c.search_dataset("g/n", "hi", mode="exact", lang="fr")
+    params = c._http.get.call_args.kwargs["params"]
+    assert params["mode"] == "exact" and params["lang"] == "fr"
+
+
+def test_search_dataset_native_delegates(monkeypatch):
+    c = _client(monkeypatch)
+    c._resolve = MagicMock(return_value=DatasetInfo._from_json(_DS_JSON))
+    nat = MagicMock()
+    nat.dataset_search.return_value = {"rows": [{"id": 42}]}
+    c._native = nat
+    assert c.search_dataset("g/n", "hi", mode="exact", lang="fr", limit=5) == [{"id": 42}]
+    nat.dataset_search.assert_called_once_with("ds-1", "hi", "exact", "fr", 5)
+    c._http.get.assert_not_called()
+
+
+def test_semantic_search(monkeypatch):
+    c = _client(monkeypatch)
+    c._native = None
+    c._resolve = MagicMock(return_value=DatasetInfo._from_json(_DS_JSON))
+    c._http.get.return_value = _resp(200, {"hits": [{"id": 9, "score": 0.8}]})
+    assert c.semantic_search("g/n", "symptoms", lang="en,fr")[0]["id"] == 9
+    assert "/semantic" in c._http.get.call_args.args[0]
+
+
+def test_optimize_embedding_search(monkeypatch):
+    c = _client(monkeypatch)
+    c._native = None
+    c._resolve = MagicMock(return_value=DatasetInfo._from_json(_DS_JSON))
+    c._http.post.return_value = _resp(200, {"status": "running"})
+    assert c.optimize_embedding_search("g/n")["status"] == "running"
+
+
+def test_word_lookup_union_intersect(monkeypatch):
+    c = _client(monkeypatch)
+    c._native = None
+    c._resolve = MagicMock(return_value=DatasetInfo._from_json(_DS_JSON))
+    c._http.get.return_value = _resp(200, {"ids": [1, 2]})
+    c.word_lookup("g/n", ["a", "b"], op="intersect", lang="fr")
+    params = c._http.get.call_args.kwargs["params"]
+    assert params["term"] == "a,b" and params["op"] == "intersect" and params["lang"] == "fr"
+
+
+def test_keyword_expand(monkeypatch):
+    c = _client(monkeypatch)
+    c._native = None
+    c._http.post.return_value = _resp(200, {"keywords": ["a", "b"], "csv": "a, b", "count": 2})
+    out = c.keyword_expand("medical terms in french", count=2)
+    assert out["count"] == 2
+    assert c._http.post.call_args.args[0] == "/datasets/keyword-expand"
+
+
+def test_derive_by_query_create(monkeypatch):
+    c = _client(monkeypatch)
+    c._native = None
+    c._resolve = MagicMock(return_value=DatasetInfo._from_json(_DS_JSON))
+    c._http.post.return_value = _resp(200, dict(_DS_JSON, name="medical-fr"))
+    out = c.derive_by_query("g/parent", "a,b", name="g/medical-fr", mode="word", lang="fr")
+    assert out.name == "medical-fr"
+    body = c._http.post.call_args.kwargs["json"]
+    assert body["mode"] == "word" and body["name"] == "g/medical-fr" and body["lang"] == "fr"
+
+
+def test_derive_by_query_native_delegates(monkeypatch):
+    c = _client(monkeypatch)
+    c._resolve = MagicMock(return_value=DatasetInfo._from_json(_DS_JSON))
+    nat = MagicMock()
+    nat.derive_dataset.return_value = dict(_DS_JSON, name="medical-fr")
+    c._native = nat
+    out = c.derive_by_query("g/parent", "a,b", name="g/medical-fr", mode="word")
+    assert out.name == "medical-fr"
+    nat.derive_dataset.assert_called_once()
+    c._http.post.assert_not_called()
+
+
+def test_derive_by_query_append(monkeypatch):
+    c = _client(monkeypatch)
+    c._native = None
+    parent = DatasetInfo._from_json(_DS_JSON)
+    target = DatasetInfo._from_json(dict(_DS_JSON, id="ds-2", name="medical-fr"))
+    c._resolve = MagicMock(side_effect=[parent, target])
+    c._http.post.return_value = _resp(200, dict(_DS_JSON, id="ds-2"))
+    c.derive_by_query("g/parent", "c,d", target_repo_id="g/medical-fr", mode="word")
+    body = c._http.post.call_args.kwargs["json"]
+    assert body["target_dataset_id"] == "ds-2" and "name" not in body
+
+
+def test_derive_by_query_requires_name_or_target(monkeypatch):
+    c = _client(monkeypatch)
+    c._native = None
+    c._resolve = MagicMock(return_value=DatasetInfo._from_json(_DS_JSON))
+    with pytest.raises(ValueError, match="name= .* target_repo_id="):
+        c.derive_by_query("g/parent", "q", mode="word")
+
+
+def test_derived_rows(monkeypatch):
+    c = _client(monkeypatch)
+    c._native = None
+    c._resolve = MagicMock(return_value=DatasetInfo._from_json(_DS_JSON))
+    c._http.get.return_value = _resp(200, {"rows": [{"k": 1}], "total": 1, "offset": 0, "limit": 50})
+    assert c.derived_rows("g/n")["total"] == 1
+    assert "/derived-rows" in c._http.get.call_args.args[0]
+
+
 # ===========================================================================
 # update / card / preview / links / derivation / delete
 # ===========================================================================
@@ -978,6 +1088,36 @@ def test_module_link_project(fake_singleton):
     assert ds_mod.link_project("g/n", "proj-1") == "P"
 
 
+def test_module_semantic_search(fake_singleton):
+    fake_singleton.semantic_search.return_value = [{"id": 2}]
+    assert ds_mod.semantic_search("g/n", "q", lang="fr") == [{"id": 2}]
+
+
+def test_module_optimize_embedding_search(fake_singleton):
+    fake_singleton.optimize_embedding_search.return_value = {"status": "ready"}
+    assert ds_mod.optimize_embedding_search("g/n") == {"status": "ready"}
+
+
+def test_module_word_lookup(fake_singleton):
+    fake_singleton.word_lookup.return_value = {"ids": [1]}
+    assert ds_mod.word_lookup("g/n", "a,b", op="union") == {"ids": [1]}
+
+
+def test_module_keyword_expand(fake_singleton):
+    fake_singleton.keyword_expand.return_value = {"csv": "a, b", "count": 2}
+    assert ds_mod.keyword_expand("prompt", count=2)["count"] == 2
+
+
+def test_module_derive_by_query(fake_singleton):
+    fake_singleton.derive_by_query.return_value = DatasetInfo._from_json(_DS_JSON)
+    assert ds_mod.derive_by_query("g/p", "q", name="g/c").name == "wmt"
+
+
+def test_module_derived_rows(fake_singleton):
+    fake_singleton.derived_rows.return_value = {"total": 3}
+    assert ds_mod.derived_rows("g/c")["total"] == 3
+
+
 def test_module_upload_file(fake_singleton):
     fake_singleton.upload_file.return_value = {"ok": True}
     assert ds_mod.upload_file("g/n", "f.txt") == {"ok": True}