convmerge 0.2.0__tar.gz

convmerge-0.2.0/.gitignore

@@ -0,0 +1,14 @@
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+dist/
+build/
+*.egg-info/
+.coverage
+htmlcov/
+*.egg
+.DS_Store

convmerge-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 convmerge contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

convmerge-0.2.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: convmerge
+Version: 0.2.0
+Summary: Fetch, normalize, and convert heterogeneous chat/instruct datasets into a single LLM training format
+Project-URL: Homepage, https://github.com/snowmuffin/convmerge
+Project-URL: Repository, https://github.com/snowmuffin/convmerge
+Project-URL: Issues, https://github.com/snowmuffin/convmerge/issues
+Author: convmerge contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: chat,dataset,jsonl,llm,sft
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: fetch
+Requires-Dist: pyyaml>=6.0; extra == 'fetch'
+Provides-Extra: fetch-all
+Requires-Dist: datasets>=2.16; extra == 'fetch-all'
+Requires-Dist: pyyaml>=6.0; extra == 'fetch-all'
+Provides-Extra: fetch-hf
+Requires-Dist: datasets>=2.16; extra == 'fetch-hf'
+Requires-Dist: pyyaml>=6.0; extra == 'fetch-hf'
+Provides-Extra: parquet
+Requires-Dist: pyarrow>=14; extra == 'parquet'
+Description-Content-Type: text/markdown
+
+# convmerge
+
+Fetch, normalize, and convert heterogeneous chat / instruct datasets into a
+**single LLM training format** (JSONL).
+
+**Repository:** [github.com/snowmuffin/convmerge](https://github.com/snowmuffin/convmerge)  
+**Status:** pre-1.0; APIs and CLI may change between minor versions.
+
+## Install
+
+```bash
+pip install convmerge                    # core: convert, normalize, dedupe, turns
+pip install "convmerge[fetch]"           # + YAML manifest fetcher (GitHub)
+pip install "convmerge[fetch-hf]"        # + HuggingFace entries (adds ``datasets``)
+pip install "convmerge[fetch-all]"       # all fetch-related extras
+pip install "convmerge[parquet]"         # + parquet streaming input
+```
+
+Or from a clone:
+
+```bash
+git clone https://github.com/snowmuffin/convmerge.git
+cd convmerge
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev,fetch-all,parquet]"
+```
+
+## The four use cases
+
+### 1. `fetch` — pull raw data from HF + GitHub via a YAML manifest
+
+```yaml
+# manifest.yaml
+version: 1
+defaults: { output_root: ./raw, resume: true }
+auth:     { hf_token_env: HF_TOKEN, github_token_env: GITHUB_TOKEN }
+datasets:
+  - { name: alpaca-ko, hf: MarkrAI/KoCommercial-Dataset, split: train }
+  - { name: orca-raw,
+      url: https://raw.githubusercontent.com/org/repo/main/data/train.jsonl }
+  - { name: repo-tree,
+      url: https://github.com/org/example-repo, ext: [".jsonl"] }
+  - { name: big-lfs,
+      url: https://github.com/org/big-lfs-repo, mode: clone, lfs: true }
+```
+
+```bash
+convmerge fetch manifest.yaml -o ./raw
+# or one-shot shortcuts:
+convmerge fetch hf://org/dataset -o ./raw --split train
+convmerge fetch https://github.com/org/repo -o ./raw --ext .jsonl
+```
+
+Tokens resolve in order CLI flag → file → env var, and are redacted from logs.
+See [docs/fetch.md](docs/fetch.md) for the full schema.
+
+### 2. `normalize` — reshape parquet / messy JSON into clean JSONL
+
+```bash
+convmerge normalize -i ./raw -o ./jsonl
+```
+
+Handles parquet (streamed via `pyarrow`), top-level JSON arrays, concatenated
+single-line JSON (`{...}{...}{...}`), and already-valid JSONL. A directory
+input is walked recursively and mirrored under the output directory.
+
+### 3. `convert` — adapter + emitter pipeline
+
+```bash
+convmerge convert -i ./jsonl/alpaca.jsonl -o ./train/alpaca.messages.jsonl \
+  --from alpaca --format messages
+
+convmerge convert -i ./jsonl/mixed.jsonl -o ./train/mixed.messages.jsonl \
+  --from auto --format messages         # auto-detecting chat adapter
+```
+
+Adapters: `alpaca`, `sharegpt`, `chat` (alias `auto`).  
+Emitters: `messages`, `alpaca`.
+
+### 4. `dedupe` / `turns` — final cleanup + train/eval split hook
+
+```bash
+convmerge dedupe -i ./train/mixed.messages.jsonl -o ./train/mixed.dedup.jsonl
+convmerge turns  -i ./train/mixed.dedup.jsonl \
+  --single-out ./train/single.jsonl \
+  --multi-out  ./train/multi.jsonl
+```
+
+See [docs/format.md](docs/format.md) for adapter / emitter schemas and
+[docs/fetch.md](docs/fetch.md) for manifest details.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). CI runs Ruff + pytest on Python
+3.10 – 3.12.
+
+```bash
+ruff check src tests
+pytest -q
+```
+
+## PyPI release (maintainers)
+
+Releases run from [`.github/workflows/publish.yml`](.github/workflows/publish.yml)
+on pushing a `v*` tag. Publishing authenticates via the **`PYPI_API_TOKEN`**
+GitHub Actions secret (a PyPI API token scoped to the `convmerge` project).
+
+1. Create an API token on [pypi.org](https://pypi.org/manage/account/token/)
+   scoped to `convmerge`.
+2. In the GitHub repo, *Settings → Secrets and variables → Actions → New
+   repository secret*, add `PYPI_API_TOKEN` with the token value.
+3. Tag and push: `git tag v0.2.0 && git push origin v0.2.0`.
+
+## Changelog
+
+[CHANGELOG.md](CHANGELOG.md)
+
+## License
+
+MIT

convmerge-0.2.0/README.md

@@ -0,0 +1,120 @@
+# convmerge
+
+Fetch, normalize, and convert heterogeneous chat / instruct datasets into a
+**single LLM training format** (JSONL).
+
+**Repository:** [github.com/snowmuffin/convmerge](https://github.com/snowmuffin/convmerge)  
+**Status:** pre-1.0; APIs and CLI may change between minor versions.
+
+## Install
+
+```bash
+pip install convmerge                    # core: convert, normalize, dedupe, turns
+pip install "convmerge[fetch]"           # + YAML manifest fetcher (GitHub)
+pip install "convmerge[fetch-hf]"        # + HuggingFace entries (adds ``datasets``)
+pip install "convmerge[fetch-all]"       # all fetch-related extras
+pip install "convmerge[parquet]"         # + parquet streaming input
+```
+
+Or from a clone:
+
+```bash
+git clone https://github.com/snowmuffin/convmerge.git
+cd convmerge
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev,fetch-all,parquet]"
+```
+
+## The four use cases
+
+### 1. `fetch` — pull raw data from HF + GitHub via a YAML manifest
+
+```yaml
+# manifest.yaml
+version: 1
+defaults: { output_root: ./raw, resume: true }
+auth:     { hf_token_env: HF_TOKEN, github_token_env: GITHUB_TOKEN }
+datasets:
+  - { name: alpaca-ko, hf: MarkrAI/KoCommercial-Dataset, split: train }
+  - { name: orca-raw,
+      url: https://raw.githubusercontent.com/org/repo/main/data/train.jsonl }
+  - { name: repo-tree,
+      url: https://github.com/org/example-repo, ext: [".jsonl"] }
+  - { name: big-lfs,
+      url: https://github.com/org/big-lfs-repo, mode: clone, lfs: true }
+```
+
+```bash
+convmerge fetch manifest.yaml -o ./raw
+# or one-shot shortcuts:
+convmerge fetch hf://org/dataset -o ./raw --split train
+convmerge fetch https://github.com/org/repo -o ./raw --ext .jsonl
+```
+
+Tokens resolve in order CLI flag → file → env var, and are redacted from logs.
+See [docs/fetch.md](docs/fetch.md) for the full schema.
+
+### 2. `normalize` — reshape parquet / messy JSON into clean JSONL
+
+```bash
+convmerge normalize -i ./raw -o ./jsonl
+```
+
+Handles parquet (streamed via `pyarrow`), top-level JSON arrays, concatenated
+single-line JSON (`{...}{...}{...}`), and already-valid JSONL. A directory
+input is walked recursively and mirrored under the output directory.
+
+### 3. `convert` — adapter + emitter pipeline
+
+```bash
+convmerge convert -i ./jsonl/alpaca.jsonl -o ./train/alpaca.messages.jsonl \
+  --from alpaca --format messages
+
+convmerge convert -i ./jsonl/mixed.jsonl -o ./train/mixed.messages.jsonl \
+  --from auto --format messages         # auto-detecting chat adapter
+```
+
+Adapters: `alpaca`, `sharegpt`, `chat` (alias `auto`).  
+Emitters: `messages`, `alpaca`.
+
+### 4. `dedupe` / `turns` — final cleanup + train/eval split hook
+
+```bash
+convmerge dedupe -i ./train/mixed.messages.jsonl -o ./train/mixed.dedup.jsonl
+convmerge turns  -i ./train/mixed.dedup.jsonl \
+  --single-out ./train/single.jsonl \
+  --multi-out  ./train/multi.jsonl
+```
+
+See [docs/format.md](docs/format.md) for adapter / emitter schemas and
+[docs/fetch.md](docs/fetch.md) for manifest details.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). CI runs Ruff + pytest on Python
+3.10 – 3.12.
+
+```bash
+ruff check src tests
+pytest -q
+```
+
+## PyPI release (maintainers)
+
+Releases run from [`.github/workflows/publish.yml`](.github/workflows/publish.yml)
+on pushing a `v*` tag. Publishing authenticates via the **`PYPI_API_TOKEN`**
+GitHub Actions secret (a PyPI API token scoped to the `convmerge` project).
+
+1. Create an API token on [pypi.org](https://pypi.org/manage/account/token/)
+   scoped to `convmerge`.
+2. In the GitHub repo, *Settings → Secrets and variables → Actions → New
+   repository secret*, add `PYPI_API_TOKEN` with the token value.
+3. Tag and push: `git tag v0.2.0 && git push origin v0.2.0`.
+
+## Changelog
+
+[CHANGELOG.md](CHANGELOG.md)
+
+## License
+
+MIT

convmerge-0.2.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "convmerge"
+version = "0.2.0"
+description = "Fetch, normalize, and convert heterogeneous chat/instruct datasets into a single LLM training format"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "convmerge contributors" }]
+keywords = ["llm", "sft", "jsonl", "chat", "dataset"]
+classifiers = [
+  "Development Status :: 2 - Pre-Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+]
+
+dependencies = []
+
+[project.optional-dependencies]
+# YAML manifest fetcher (GitHub raw / Trees API / git clone). Uses stdlib urllib for HTTP.
+fetch = ["pyyaml>=6.0"]
+# HuggingFace support for fetch (delegates to the ``datasets`` library).
+fetch-hf = ["pyyaml>=6.0", "datasets>=2.16"]
+# Alias: everything fetch-related.
+fetch-all = ["pyyaml>=6.0", "datasets>=2.16"]
+# Parquet streaming input for normalize.
+parquet = ["pyarrow>=14"]
+dev = ["pytest>=8.0", "ruff>=0.4"]
+
+[project.scripts]
+convmerge = "convmerge.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/snowmuffin/convmerge"
+Repository = "https://github.com/snowmuffin/convmerge"
+Issues = "https://github.com/snowmuffin/convmerge/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/convmerge"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

convmerge-0.2.0/src/convmerge/__init__.py

@@ -0,0 +1,3 @@
+"""convmerge — merge heterogeneous sources into a single LLM training format."""
+
+__version__ = "0.2.0"

convmerge-0.2.0/src/convmerge/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m convmerge``."""
+
+from convmerge.cli import main
+
+if __name__ == "__main__":
+    main()

convmerge-0.2.0/src/convmerge/adapters/__init__.py

@@ -0,0 +1,28 @@
+"""Source-format adapters: raw records → TrainingExample."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator
+from typing import Any
+
+from convmerge.adapters.alpaca import iter_from_alpaca_line
+from convmerge.adapters.chat import iter_from_chat_line
+from convmerge.adapters.sharegpt import iter_from_sharegpt_line
+from convmerge.models import TrainingExample
+
+AdapterFn = Callable[[dict[str, Any]], Iterator[TrainingExample]]
+
+ADAPTERS: dict[str, AdapterFn] = {
+    "alpaca": iter_from_alpaca_line,
+    "sharegpt": iter_from_sharegpt_line,
+    "chat": iter_from_chat_line,
+    # ``auto`` is an alias for ``chat`` since the chat adapter is already auto-detecting.
+    "auto": iter_from_chat_line,
+}
+
+
+def get_adapter(name: str) -> AdapterFn:
+    if name not in ADAPTERS:
+        known = ", ".join(sorted(ADAPTERS))
+        raise ValueError(f"Unknown adapter {name!r}. Choose one of: {known}")
+    return ADAPTERS[name]

convmerge-0.2.0/src/convmerge/adapters/alpaca.py

@@ -0,0 +1,38 @@
+"""Alpaca-style instruction / input / output → TrainingExample."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+from convmerge.models import ChatMessage, TrainingExample
+
+
+def iter_from_alpaca_line(record: dict[str, Any]) -> Iterator[TrainingExample]:
+    """
+    One JSON object per line: instruction, optional input, output.
+
+    Maps to a single user message + single assistant message.
+    """
+    instruction = (record.get("instruction") or "").strip()
+    inp = (record.get("input") or "").strip()
+    output = (record.get("output") or "").strip() or (record.get("response") or "").strip()
+
+    user_parts = [instruction]
+    if inp:
+        user_parts.append(inp)
+    user_content = "\n".join(user_parts).strip()
+
+    if not user_content and not output:
+        return
+
+    messages: list[ChatMessage] = []
+    if user_content:
+        messages.append(ChatMessage(role="user", content=user_content))
+    if output:
+        messages.append(ChatMessage(role="assistant", content=output))
+
+    if not messages:
+        return
+
+    yield TrainingExample(messages=messages, meta={"source": "alpaca"})

convmerge-0.2.0/src/convmerge/adapters/chat.py

@@ -0,0 +1,205 @@
+"""Auto-detecting chat adapter.
+
+Routes a raw record to the right internal shape by looking at which keys are
+present. Handles the common messy shapes seen across SFT datasets:
+
+- ``messages`` / ``conversation`` / ``conversations`` lists with
+  ``{role, content}`` or ``{from, value}`` entries.
+- Pairwise preference rows (``conversation_a`` / ``conversation_b``), with an
+  optional ``winner`` field; emits only the winner branch by default.
+- Plain ``text`` strings (yielded as a single assistant message).
+- Alpaca-style ``instruction`` / ``input`` / ``output`` (delegates to the
+  existing alpaca adapter).
+
+Users can override the key lists and role map to teach it about bespoke schemas
+without writing a new adapter from scratch.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+from convmerge.adapters.alpaca import iter_from_alpaca_line
+from convmerge.models import ChatMessage, TrainingExample
+
+# Default mapping from common ShareGPT-style ``from`` values onto standard roles.
+DEFAULT_ROLE_MAP: dict[str, str] = {
+    "human": "user",
+    "user": "user",
+    "gpt": "assistant",
+    "assistant": "assistant",
+    "bing": "assistant",
+    "bot": "assistant",
+    "system": "system",
+}
+
+# Keys searched for the chat-list container, in priority order.
+DEFAULT_CONVERSATION_KEYS: tuple[str, ...] = ("messages", "conversation", "conversations")
+
+# Keys treated as role labels inside a chat-list entry.
+DEFAULT_ROLE_KEYS: tuple[str, ...] = ("role", "from")
+
+# Keys treated as message content inside a chat-list entry.
+DEFAULT_CONTENT_KEYS: tuple[str, ...] = ("content", "value", "text")
+
+
+def iter_from_chat_line(
+    record: dict[str, Any],
+    *,
+    conversation_keys: tuple[str, ...] = DEFAULT_CONVERSATION_KEYS,
+    role_keys: tuple[str, ...] = DEFAULT_ROLE_KEYS,
+    content_keys: tuple[str, ...] = DEFAULT_CONTENT_KEYS,
+    role_map: dict[str, str] | None = None,
+    pairwise_mode: str = "winner",
+    instruction_keys: tuple[str, ...] = ("instruction", "question", "prompt"),
+    output_keys: tuple[str, ...] = ("output", "response", "answer"),
+    input_keys: tuple[str, ...] = ("input", "context"),
+) -> Iterator[TrainingExample]:
+    """Yield zero or more :class:`TrainingExample` from a single raw record.
+
+    ``pairwise_mode`` controls how ``conversation_a`` / ``conversation_b`` rows
+    are handled:
+
+    - ``"winner"`` (default): emit only the branch named by the ``winner`` field;
+      emit nothing when ``winner`` is absent or unrecognised.
+    - ``"both"``: emit both branches as independent examples.
+    - ``"a"`` / ``"b"``: always emit the chosen branch.
+    """
+    role_map = role_map or DEFAULT_ROLE_MAP
+
+    if "conversation_a" in record and "conversation_b" in record:
+        yield from _iter_pairwise(
+            record,
+            role_keys=role_keys,
+            content_keys=content_keys,
+            role_map=role_map,
+            pairwise_mode=pairwise_mode,
+        )
+        return
+
+    for key in conversation_keys:
+        convs = record.get(key)
+        if isinstance(convs, list) and convs:
+            msgs = _coerce_messages(
+                convs, role_keys=role_keys, content_keys=content_keys, role_map=role_map
+            )
+            if msgs:
+                yield TrainingExample(messages=msgs, meta={"source": "chat"})
+            return
+
+    txt = record.get("text")
+    if isinstance(txt, str) and txt.strip():
+        yield TrainingExample(
+            messages=[ChatMessage(role="assistant", content=txt.strip())],
+            meta={"source": "chat:text"},
+        )
+        return
+
+    # Fall back to the alpaca adapter, but let callers override the key priority.
+    remapped = _remap_for_alpaca(record, instruction_keys, input_keys, output_keys)
+    if remapped is not None:
+        yield from iter_from_alpaca_line(remapped)
+
+
+def _iter_pairwise(
+    record: dict[str, Any],
+    *,
+    role_keys: tuple[str, ...],
+    content_keys: tuple[str, ...],
+    role_map: dict[str, str],
+    pairwise_mode: str,
+) -> Iterator[TrainingExample]:
+    a = record.get("conversation_a")
+    b = record.get("conversation_b")
+    winner = str(record.get("winner") or "").lower().strip()
+
+    branches: list[tuple[str, Any]] = []
+    if pairwise_mode == "both":
+        branches = [("a", a), ("b", b)]
+    elif pairwise_mode == "a":
+        branches = [("a", a)]
+    elif pairwise_mode == "b":
+        branches = [("b", b)]
+    elif pairwise_mode == "winner":
+        if winner in ("model_a", "a"):
+            branches = [("a", a)]
+        elif winner in ("model_b", "b"):
+            branches = [("b", b)]
+        # Tie / unknown: emit nothing.
+    else:
+        raise ValueError(
+            f"Unknown pairwise_mode {pairwise_mode!r}. Use 'winner', 'both', 'a', or 'b'."
+        )
+
+    for label, convs in branches:
+        if not isinstance(convs, list) or not convs:
+            continue
+        msgs = _coerce_messages(
+            convs, role_keys=role_keys, content_keys=content_keys, role_map=role_map
+        )
+        if msgs:
+            yield TrainingExample(
+                messages=msgs,
+                meta={"source": "chat:pairwise", "branch": label},
+            )
+
+
+def _coerce_messages(
+    convs: list[Any],
+    *,
+    role_keys: tuple[str, ...],
+    content_keys: tuple[str, ...],
+    role_map: dict[str, str],
+) -> list[ChatMessage]:
+    out: list[ChatMessage] = []
+    for item in convs:
+        if not isinstance(item, dict):
+            continue
+        role_raw: str | None = None
+        for rk in role_keys:
+            v = item.get(rk)
+            if isinstance(v, str) and v.strip():
+                role_raw = v.strip().lower()
+                break
+        if role_raw is None:
+            continue
+        role = role_map.get(role_raw, role_raw)
+
+        content: str | None = None
+        for ck in content_keys:
+            v = item.get(ck)
+            if isinstance(v, str):
+                content = v
+                break
+        if content is None:
+            continue
+        out.append(ChatMessage(role=role, content=content))
+    return out
+
+
+def _remap_for_alpaca(
+    record: dict[str, Any],
+    instruction_keys: tuple[str, ...],
+    input_keys: tuple[str, ...],
+    output_keys: tuple[str, ...],
+) -> dict[str, Any] | None:
+    """Pick the first matching key for each slot and return a standard alpaca row."""
+    instr = _first_string(record, instruction_keys)
+    out = _first_string(record, output_keys)
+    if instr is None and out is None:
+        return None
+    inp = _first_string(record, input_keys) or ""
+    return {
+        "instruction": instr or "",
+        "input": inp,
+        "output": out or "",
+    }
+
+
+def _first_string(record: dict[str, Any], keys: tuple[str, ...]) -> str | None:
+    for k in keys:
+        v = record.get(k)
+        if isinstance(v, str) and v.strip():
+            return v
+    return None