haplohub-cli 3.0.0__tar.gz → 3.2.0__tar.gz

{haplohub_cli-3.0.0 → haplohub_cli-3.2.0}/.github/workflows/on_pr.yml

@@ -10,7 +10,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
 
     steps:
       - uses: actions/checkout@v6

{haplohub_cli-3.0.0 → haplohub_cli-3.2.0}/.github/workflows/on_push_main.yml

@@ -65,7 +65,7 @@ jobs:
           name: Packages
           path: dist
       - name: Sign the dists with Sigstore
-        uses: sigstore/gh-action-sigstore-python@v3.3.0
+        uses: sigstore/gh-action-sigstore-python@v3.5.0
         with:
           inputs: >-
             ./dist/*.tar.gz

haplohub_cli-3.2.0/AGENTS.md

@@ -0,0 +1,36 @@
+# haplohub-cli
+
+Command line interface for the HaploHub API. A Click application (`haplohub` entry
+point) that wraps the auto-generated `haplohub` Python SDK. Python 3.10+, managed
+with uv, released to PyPI.
+
+Start with [docs/index.md](docs/index.md). It is the table of contents for the
+docs and the entry point for anything deeper than this file.
+
+## Commands
+
+```sh
+uv sync --dev                # install (uses the local ../haplohub-python SDK checkout)
+uv run pytest                # tests
+uv run ruff format . && uv run ruff check .
+uv run haplohub --help       # run the CLI
+```
+
+Pre-commit hooks run ruff and the test suite on every commit.
+
+## Architecture
+
+Commands do not print results. They return SDK response models, and the
+`result_callback` in `haplohub_cli/cli.py` renders them through the formatter
+registry in `haplohub_cli/formatters/`, which is keyed on the model type.
+Models without a registered formatter render via the generic fallback in
+`formatters/generic_table.py` (wrapper responses unwrap to `.result`; list and
+single models become introspected tables), so write a formatter only when the
+generic output needs curating. `-f json` bypasses formatters entirely. `haplohub_cli/core/api/client.py` exposes
+lazy per-resource API accessors over one authenticated SDK client. Command groups
+in `haplohub_cli/commands/` mirror API resources. Tests live in `tests/`
+subpackages next to the code they cover.
+
+Model and request class names come from the generated SDK. When the SDK
+regenerates, renames ripple into commands and formatters here. See
+[docs/sdk-coupling.md](docs/sdk-coupling.md) before touching the dependency.

haplohub_cli-3.2.0/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

{haplohub_cli-3.0.0 → haplohub_cli-3.2.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: haplohub-cli
-Version: 3.0.0
+Version: 3.2.0
 Summary: HaploHub Command Line Interface
 Author-email: Mike Polcari <mike@haplotype-labs.com>, Ilya Khrustalev <ilya@haplotype-labs.com>
-Requires-Python: >=3.8
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: click>=8.1.8
-Requires-Dist: haplohub<4,>=3.0.1
+Requires-Dist: haplohub<4,>=3.1.0
 Requires-Dist: pendulum>=3.0.0
 Requires-Dist: requests>=2.32.0
 Requires-Dist: rich>=13.9.4

haplohub_cli-3.2.0/docs/index.md

@@ -0,0 +1,14 @@
+# Docs
+
+Table of contents for this repo's documentation. Read the file that matches your
+task before starting it.
+
+- [sdk-coupling.md](sdk-coupling.md) - How this CLI depends on the generated
+  `haplohub` SDK: the editable local override, the version constraint policy, and
+  why CI stays red until the matching SDK version is on real PyPI.
+- [testing.md](testing.md) - Test conventions: unittest style, `CliRunner`,
+  mocking the API client, and the import-time rules that the smoke test enforces.
+- [release.md](release.md) - Versioning and release flow: setuptools_scm tags,
+  Test PyPI vs PyPI publishing, the CI matrix, and branch protection gotchas.
+- [stage-verification.md](stage-verification.md) - How to verify the CLI against
+  the stage environment end to end without disturbing prod config or real data.

haplohub_cli-3.2.0/docs/release.md

@@ -0,0 +1,26 @@
+# Release and CI
+
+## Versioning
+
+Versions come from git tags via setuptools_scm (`v3.1.0` style, written to
+`haplohub_cli/_version.py` at build time). There is no version field to edit in
+`pyproject.toml`. The CLI version loosely tracks the API and SDK major version.
+
+## Publishing
+
+- Push to `main` publishes a dev version (for example `3.0.1.dev2`) to Test PyPI.
+- Pushing a `vX.Y.Z` tag publishes a release to PyPI.
+
+So cutting a release is: merge to main, then tag `vX.Y.Z` and push the tag.
+Sensibly, tag only after the matching API version is deployed to prod and the
+matching SDK release exists on PyPI.
+
+## CI
+
+`on_pr.yml` runs a lint + test matrix on Python 3.10 through 3.13 with
+`uv sync --no-sources` (see sdk-coupling.md for what that implies).
+
+Branch protection on `main` requires the matrix job names as status checks
+(`lint (3.10)` ... `lint (3.13)`). If you change the matrix, update the required
+checks in the branch protection settings too, otherwise merges get blocked on
+check names that no longer exist and need an admin override.

haplohub_cli-3.2.0/docs/sdk-coupling.md

@@ -0,0 +1,43 @@
+# SDK coupling
+
+The `haplohub` dependency is an OpenAPI-generated SDK. This repo contains no API
+models of its own; every request and response class is imported from the SDK.
+
+## Local development
+
+`[tool.uv.sources]` overrides `haplohub` to an editable install of the sibling
+checkout `../haplohub-python`. Locally you always run against that checkout's
+current state, whatever version PyPI has. Keep this in mind when results look
+newer or older than the released SDK.
+
+## Version constraint
+
+`pyproject.toml` pins a range like `haplohub>=3.1.0,<4`. Policy:
+
+- The lower bound is the oldest SDK release whose API surface this code uses.
+  Raise it whenever code starts using something newer.
+- The upper bound excludes the next major.
+- Do not lower the bound past 3.0.1: the 3.0.0 release on PyPI is broken
+  (published from the wrong spec, later yanked).
+
+## CI resolves from real PyPI
+
+CI installs with `uv sync --no-sources`, which ignores the editable override and
+resolves `haplohub` from pypi.org only. Test PyPI is never consulted.
+Consequence: a PR that needs an unreleased SDK version cannot go green. Release
+the SDK first (see the release docs in `../haplohub-python`), then land the CLI
+change.
+
+## Surviving SDK regenerations
+
+Regenerations rename response models (for example, the 3.0 change replaced
+`PaginatedResponse*Schema` wrappers with per-operation models like
+`ListMembersResponse`). When bumping the SDK:
+
+1. Diff the names the CLI imports against the new SDK exports, and check the
+   field shapes (`.result`, `.items`, `total_count`) at every call site.
+2. Update commands and formatter registrations together; formatters are keyed on
+   model classes and fail silently at registration time if a class is gone. A
+   model that loses its formatter falls back to the generic table renderer, so
+   the symptom is degraded (uncurated) output rather than a crash.
+3. Run the test suite. The CLI `--help` smoke test catches import-time breakage.

haplohub_cli-3.2.0/docs/stage-verification.md

@@ -0,0 +1,30 @@
+# Stage verification
+
+Unit tests never touch the network, so real endpoint behavior is verified
+manually against the stage environment.
+
+## Environment switching
+
+```sh
+haplohub config switch https://api.stage.haplohub.com   # switch to stage
+haplohub config switch https://api.haplohub.com         # switch back when done
+```
+
+Credentials are stored per environment in `~/.haplohub/credentials.json`, so
+switching does not require a new login if stage credentials already exist.
+Always switch back to prod at the end.
+
+## Practices
+
+- Use `haplohub -f json <command>` for output you want to parse in scripts.
+- Read endpoints: run against existing cohorts, found via `haplohub cohort list`.
+  Prefer a large cohort when exercising pagination.
+- Mutating endpoints: create a clearly named scratch cohort, do all
+  create/update/delete work inside it, then delete the cohort. Never mutate
+  cohorts you did not create.
+- Uploads materialize asynchronously; a file appears in `file list` some seconds
+  after `file upload` returns.
+- Variant queries can take minutes on first access to a sample (cold storage)
+  and run in seconds afterwards.
+- Endpoints that launch real work (algorithm runs, report generation) are
+  expensive on stage. Skip them in routine smoke tests and note the gap instead.

haplohub_cli-3.2.0/docs/testing.md

@@ -0,0 +1,29 @@
+# Testing
+
+Run with `uv run pytest`. Pre-commit runs the suite on every commit, so a
+failing test blocks commits too.
+
+## Conventions
+
+- unittest `TestCase` classes, plain asserts from unittest, pytest as the runner.
+- Tests live in a `tests/` subpackage next to the code they cover
+  (`haplohub_cli/commands/tests/`, `haplohub_cli/auth/tests/`, ...).
+- Invoke commands through `click.testing.CliRunner` and assert on
+  `result.exit_code` and `result.output`.
+- Mock the API at the client boundary:
+  `patch("haplohub_cli.commands.<module>.client")`. Build fake responses with
+  `types.SimpleNamespace`; do not construct real SDK models in unit tests.
+- No network in tests. Anything that talks to a real environment belongs to
+  stage verification, not the suite.
+
+## Import-time rules
+
+`cli.py` imports every command module at startup, so module-level code in
+`commands/` runs on every invocation, including `--help`. Two consequences:
+
+- Syntax and annotations evaluated at import must work on the oldest supported
+  Python (3.10, see `requires-python`).
+- Keep module level free of slow work or network calls.
+
+`haplohub_cli/tests/test_cli.py` invokes `--help` to catch import-time breakage
+(SDK renames, bad annotations). Keep that test passing; it is the canary.

{haplohub_cli-3.0.0 → haplohub_cli-3.2.0}/haplohub_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '3.0.0'
-__version_tuple__ = version_tuple = (3, 0, 0)
+__version__ = version = '3.2.0'
+__version_tuple__ = version_tuple = (3, 2, 0)
 
-__commit_id__ = commit_id = 'g391c0fcf5'
+__commit_id__ = commit_id = 'gd9453247c'

{haplohub_cli-3.0.0 → haplohub_cli-3.2.0}/haplohub_cli/auth/oauth_client.py

@@ -28,6 +28,9 @@ class AuthRequest:
             f"&scope={' '.join(self.scopes)}"
             f"&code_challenge={self.code_challenge}"
             f"&code_challenge_method=S256"
+            # WorkOS routes the request to the hosted AuthKit sign-in; without
+            # a provider the authorize endpoint rejects the request.
+            f"&provider=authkit"
         )
 
     def generate_code_verifier(self):

{haplohub_cli-3.0.0 → haplohub_cli-3.2.0}/haplohub_cli/cli.py

@@ -44,12 +44,6 @@ def formatter_callback(ctx, result, **_):
             click.echo(json.dumps(result, default=str))
         return
 
-    if not formatter_registry.has_formatter(type(result)):
-        from pprint import pprint
-
-        pprint(result)
-        return
-
     formatter_registry.format(result)
 
 

{haplohub_cli-3.0.0 → haplohub_cli-3.2.0}/haplohub_cli/commands/file.py

@@ -25,11 +25,36 @@ def file():
 @click.option("--cohort", "-c", type=click.STRING, required=True)
 @click.option("--path", "-p", type=click.STRING, required=False)
 @click.option("--recursive", "-r", is_flag=True, required=False)
-def list(cohort: str, path: str = None, recursive: bool = False):
+@click.option("--sample", "-s", type=click.STRING, required=False, help="Filter by sample id")
+@click.option("--sample-external-id", "-xs", type=click.STRING, required=False, help="Filter by sample external id")
+@click.option("--member", "-m", type=click.STRING, required=False, help="Filter by member id")
+@click.option("--member-external-id", "-xm", type=click.STRING, required=False, help="Filter by member external id")
+@click.option("--search", type=click.STRING, required=False, help="Search file names")
+@click.option("--offset", type=click.IntRange(min=0), required=False, help="Skip the first N files [default: 0]")
+@click.option("--limit", type=click.IntRange(1, 1000), required=False, help="Page size [default: 100, max: 1000]")
+def list(
+    cohort: str,
+    path: str = None,
+    recursive: bool = False,
+    sample: str = None,
+    sample_external_id: str = None,
+    member: str = None,
+    member_external_id: str = None,
+    search: str = None,
+    offset: int = None,
+    limit: int = None,
+):
     return client.file.list_files(
         cohort,
         recursive=recursive,
         path=path,
+        sample_id=sample,
+        sample_external_id=sample_external_id,
+        member_id=member,
+        member_external_id=member_external_id,
+        search=search,
+        offset=offset,
+        limit=limit,
     )
 
 
@@ -67,13 +92,20 @@ def _resolve_file_id(cohort: str, file_path: str) -> str:
     """Look a file up by its location.
 
     The API deletes by id only - unlike downloads, which have a by-path endpoint - so
-    the path is resolved here to keep --file-path working on both commands.
+    the path is resolved here to keep --file-path working on both commands. Listings
+    are paginated server-side, so pages are walked until the file is found.
     """
-    listing = client.file.list_files(cohort, recursive=True)
     wanted = file_path.lstrip("/")
-    for entry in listing.result.files:
-        if entry.location == wanted:
-            return entry.id
+    offset = 0
+    while True:
+        result = client.file.list_files(cohort, recursive=True, offset=offset, limit=1000).result
+        for entry in result.files:
+            if entry.location == wanted:
+                return entry.id
+
+        offset += len(result.files)
+        if not result.files or offset >= result.total_count:
+            break
 
     raise click.ClickException(f"No file at '{file_path}' in cohort {cohort}.")
 

haplohub_cli-3.2.0/haplohub_cli/commands/tests/test_file.py

@@ -0,0 +1,56 @@
+from types import SimpleNamespace
+from unittest import TestCase
+from unittest.mock import patch
+
+import click
+
+from haplohub_cli.commands.file import _resolve_file_id
+
+COHORT = "coh-abc123"
+
+
+def page(locations, total_count, first_id="fil-1"):
+    files = [SimpleNamespace(id=f"{first_id}-{i}", location=loc) for i, loc in enumerate(locations)]
+    return SimpleNamespace(result=SimpleNamespace(files=files, total_count=total_count))
+
+
+class ResolveFileIdTestCase(TestCase):
+    def test_finds_file_on_first_page(self):
+        with patch("haplohub_cli.commands.file.client") as client:
+            client.file.list_files.return_value = page(["a.vcf", "b.vcf"], total_count=2)
+
+            file_id = _resolve_file_id(COHORT, "/b.vcf")
+
+        self.assertEqual(file_id, "fil-1-1")
+        client.file.list_files.assert_called_once_with(COHORT, recursive=True, offset=0, limit=1000)
+
+    def test_walks_pages_until_found(self):
+        pages = [
+            page([f"page1/{i}.vcf" for i in range(1000)], total_count=1001),
+            page(["deep/target.vcf"], total_count=1001, first_id="fil-2"),
+        ]
+        with patch("haplohub_cli.commands.file.client") as client:
+            client.file.list_files.side_effect = pages
+
+            file_id = _resolve_file_id(COHORT, "deep/target.vcf")
+
+        self.assertEqual(file_id, "fil-2-0")
+        self.assertEqual(client.file.list_files.call_count, 2)
+        client.file.list_files.assert_called_with(COHORT, recursive=True, offset=1000, limit=1000)
+
+    def test_raises_when_not_found(self):
+        with patch("haplohub_cli.commands.file.client") as client:
+            client.file.list_files.return_value = page(["a.vcf"], total_count=1)
+
+            with self.assertRaises(click.ClickException):
+                _resolve_file_id(COHORT, "missing.vcf")
+
+    def test_stops_on_empty_page(self):
+        # A stale total_count must not loop forever when the server returns no more files.
+        with patch("haplohub_cli.commands.file.client") as client:
+            client.file.list_files.return_value = page([], total_count=5)
+
+            with self.assertRaises(click.ClickException):
+                _resolve_file_id(COHORT, "missing.vcf")
+
+        client.file.list_files.assert_called_once()

haplohub_cli-3.2.0/haplohub_cli/core/api/client.py

@@ -0,0 +1,40 @@
+from functools import cached_property
+
+import click
+from haplohub import ApiClient, Configuration
+
+from haplohub_cli import settings
+from haplohub_cli.auth.token_storage import TokenStorage
+from haplohub_cli.config.config_manager import config_manager
+
+
+class Client:
+    token_storage = TokenStorage(settings.CREDENTIALS_FILE)
+
+    @cached_property
+    def client(self) -> ApiClient:
+        api_url = config_manager.config.api_url
+
+        if not self.token_storage.credentials_exist(api_url):
+            raise click.ClickException(f"No credentials found for {api_url}. Run `haplohub login` first.")
+
+        if self.token_storage.has_api_key(api_url):
+            config = Configuration(
+                host=api_url,
+                api_key={"ApiKeyAuth": self.token_storage.get_api_key(api_url)},
+            )
+        else:
+            config = Configuration(
+                host=api_url,
+                access_token=self.token_storage.get_access_token(api_url),
+            )
+        return ApiClient(config)
+
+    def __getattr__(self, name: str):
+        # client.cohort -> ApiClient.cohort_api, client.member_report -> ApiClient.member_report_api, ...
+        if name.startswith("_"):
+            raise AttributeError(name)
+        return getattr(self.client, f"{name}_api")
+
+
+client = Client()

{haplohub_cli-3.0.0 → haplohub_cli-3.2.0}/haplohub_cli/core/tests/test_checksum.py

@@ -48,8 +48,9 @@ class ChecksumTestCase(TestCase):
                 return False
 
         fake_file = FakeFile(data)
-        with patch("haplohub_cli.core.checksum.open", return_value=fake_file) as mocked_open, patch(
-            "haplohub_cli.core.checksum.CHUNK_SIZE", 4
+        with (
+            patch("haplohub_cli.core.checksum.open", return_value=fake_file) as mocked_open,
+            patch("haplohub_cli.core.checksum.CHUNK_SIZE", 4),
         ):
             result = calculate_checksum("dummy/path")
 

{haplohub_cli-3.0.0 → haplohub_cli-3.2.0}/haplohub_cli/formatters/__init__.py

@@ -2,11 +2,7 @@
 from .algorithm import *
 from .algorithm_result import *
 from .biomarker import *
-from .cohort import *
 from .config import *
 from .file import *
 from .generic import *
-from .member import *
-from .metadata import *
-from .sample import *
 from .variant import *

{haplohub_cli-3.0.0 → haplohub_cli-3.2.0}/haplohub_cli/formatters/algorithm.py

@@ -3,7 +3,6 @@ from typing import Optional
 from haplohub import (
     AlgorithmSchema,
     AlgorithmVersionSchema,
-    GetAlgorithmResponse,
     ListAlgorithmsResponse,
 )
 from rich.table import Table
@@ -28,11 +27,6 @@ def format_algorithm(data: AlgorithmSchema):
     return table
 
 
-@register(GetAlgorithmResponse)
-def format_single_algorithm(data: GetAlgorithmResponse):
-    return format_algorithm(data.result)
-
-
 @register(ListAlgorithmsResponse)
 def format_algorithms(data: ListAlgorithmsResponse):
     table = Table(title="Algorithms", caption=f"Total: {data.total_count}")

{haplohub_cli-3.0.0 → haplohub_cli-3.2.0}/haplohub_cli/formatters/algorithm_result.py

@@ -1,7 +1,6 @@
 import json
 
 from haplohub import (
-    AlgorithmResultResponse,
     AlgorithmResultSchema,
     ListAlgorithmResultsResponse,
 )
@@ -32,11 +31,6 @@ def format_algorithm_result(data: AlgorithmResultSchema):
     return table
 
 
-@register(AlgorithmResultResponse)
-def format_single_algorithm_result(data: AlgorithmResultResponse):
-    return format_algorithm_result(data.result)
-
-
 @register(ListAlgorithmResultsResponse)
 def format_algorithm_results(data: ListAlgorithmResultsResponse):
     table = Table(title="Algorithm Results", caption=f"Total: {data.total_count}")

haplohub_cli-3.2.0/haplohub_cli/formatters/file.py

@@ -0,0 +1,26 @@
+from haplohub import ListFilesResponse
+from rich.table import Table
+
+from haplohub_cli.formatters import utils
+from haplohub_cli.formatters.decorators import register
+
+
+@register(ListFilesResponse)
+def format_files(data: ListFilesResponse):
+    result = data.result
+    table = Table(
+        title=f"Contents of {result.location or 'ROOT'}",
+        caption=f"Files: {len(result.files)} of {result.total_count}, dirs: {len(result.dirs)}",
+    )
+    table.add_column("Id")
+    table.add_column("File name")
+    table.add_column("Size")
+    table.add_column("Created")
+
+    for dir in result.dirs:
+        table.add_row("DIR", dir.location + "/")
+
+    for file in result.files:
+        table.add_row(utils.format_id(file.id), file.location, str(file.file_size), utils.format_dt(file.created))
+
+    return table

haplohub_cli-3.2.0/haplohub_cli/formatters/formatter_registry.py

@@ -0,0 +1,35 @@
+from pprint import pprint
+
+from pydantic import BaseModel
+from rich.console import Console
+
+from haplohub_cli.formatters.generic_table import build_generic
+
+
+class FormatterRegistry:
+    def __init__(self):
+        self.formatters = {}
+        self.console = Console()
+
+    def register_formatter(self, model_type, formatter):
+        self.formatters[model_type] = formatter
+
+    def format(self, model):
+        formatter = self.formatters.get(type(model))
+        if formatter is not None:
+            self.console.print(formatter(model))
+            return
+
+        # Response wrappers (XResponse with a `result` payload) render as their payload.
+        if isinstance(model, BaseModel) and "result" in type(model).model_fields:
+            self.format(model.result)
+            return
+
+        output = build_generic(model)
+        if output is None:
+            pprint(model)
+            return
+        self.console.print(output)
+
+
+formatter_registry = FormatterRegistry()

haplohub_cli-3.2.0/haplohub_cli/formatters/generic_table.py

@@ -0,0 +1,104 @@
+"""Fallback rendering for SDK models without a registered formatter.
+
+Builds rich tables by introspecting pydantic model fields, so new SDK
+response types render without any formatter code. Register a formatter
+only when the generic output needs curating.
+"""
+
+import json
+import re
+import typing
+from datetime import date, datetime
+
+from pydantic import BaseModel
+from pydantic_core import to_jsonable_python
+from rich.table import Table
+
+from haplohub_cli.formatters import utils
+
+LIST_TRUNCATE = 50
+
+
+def build_generic(model):
+    if not isinstance(model, BaseModel):
+        return None
+    if "items" in type(model).model_fields:
+        return _list_table(model)
+    return _single_table(model)
+
+
+def _list_table(model):
+    items = model.items or []
+    total = getattr(model, "total_count", None)
+    table = Table(title=_title(type(model)), caption=f"Total: {total if total is not None else len(items)}")
+
+    item_type = _item_type(type(model))
+    if item_type is not None:
+        fields = _ordered_fields(item_type)
+        for field in fields:
+            table.add_column(_header(field))
+        for item in items:
+            table.add_row(*(_render_value(getattr(item, field), truncate_to=LIST_TRUNCATE) for field in fields))
+    else:
+        table.add_column("Value")
+        for item in items:
+            table.add_row(_render_value(item))
+
+    return table
+
+
+def _single_table(model):
+    fields = _ordered_fields(type(model))
+    caption = f"Id: {model.id}" if "id" in fields else None
+    table = Table(title=_title(type(model)), caption=caption)
+    for field in fields:
+        table.add_column(_header(field))
+    table.add_row(*(_render_value(getattr(model, field)) for field in fields))
+    return table
+
+
+def _item_type(model_type):
+    annotation = model_type.model_fields["items"].annotation
+    for arg in typing.get_args(annotation):
+        if isinstance(arg, type) and issubclass(arg, BaseModel):
+            return arg
+    return None
+
+
+def _ordered_fields(model_type):
+    # SDK models list fields alphabetically; pin identity up front and timestamps last.
+    fields = list(model_type.model_fields)
+    head = [f for f in ("id", "name") if f in fields]
+    tail = [f for f in fields if f in ("created", "modified")]
+    return head + [f for f in fields if f not in head and f not in tail] + tail
+
+
+def _header(field: str) -> str:
+    return field.replace("_", " ").title()
+
+
+def _title(model_type) -> str:
+    name = model_type.__name__
+    for prefix in ("List", "Get"):
+        name = name.removeprefix(prefix)
+    for suffix in ("Response", "Schema"):
+        name = name.removesuffix(suffix)
+    return re.sub(r"(?<=[a-z0-9])(?=[A-Z])", " ", name) or model_type.__name__
+
+
+def _render_value(value, truncate_to: int | None = None) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, datetime):
+        return utils.format_dt(value)
+    if isinstance(value, date):
+        return utils.format_date(value)
+    if hasattr(value, "actual_instance"):
+        text = utils.format_id(value)
+    elif isinstance(value, (dict, list, BaseModel)):
+        text = json.dumps(to_jsonable_python(value), default=str)
+    else:
+        text = str(value)
+    if truncate_to is not None:
+        text = utils.truncate(text, truncate_to)
+    return text