okf-loremaster 0.1.0__py3-none-any.whl

okf_loremaster/__init__.py

@@ -0,0 +1,9 @@
+"""OKF Loremaster — task-scoped biomedical literature bundles in Open Knowledge Format."""
+
+from __future__ import annotations
+
+__all__ = ["DISPLAY_NAME", "__version__"]
+
+__version__ = "0.1.0"
+
+DISPLAY_NAME = "OKF Loremaster"

okf_loremaster/cli.py

@@ -0,0 +1,483 @@
+"""Command-line interface for OKF Loremaster.
+
+Heavy modules are imported inside the commands that need them. `litellm` and `chromadb`
+each cost seconds to import, and `--help` should not pay for either. The commands that
+touch a bundle rather than build one — `validate`, `export`, `inspect` — import nothing
+from the graph at all, so they run against a directory on a machine with no API key.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Iterator
+from contextlib import contextmanager
+from importlib import resources
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.markup import escape
+
+from okf_loremaster import DISPLAY_NAME, __version__
+from okf_loremaster.finalize import Finalize
+
+console = Console(stderr=True)
+
+app = typer.Typer(
+    name="okf-loremaster",
+    help=f"{DISPLAY_NAME} — build a task-scoped biomedical literature bundle "
+    "from PubMed/PMC in Open Knowledge Format.",
+    no_args_is_help=True,
+    add_completion=False,
+    rich_markup_mode="rich",
+)
+
+
+@contextmanager
+def _reported() -> Iterator[None]:
+    """Turn the failures a user can act on into one line and an exit code.
+
+    Config, file and interrupt errors are the user's to fix and a traceback tells them
+    nothing. Everything else propagates: a bug in a node should look like one.
+    """
+    from okf_loremaster.config import ConfigError
+    from okf_loremaster.run import RunInterrupted
+
+    try:
+        yield
+    except RunInterrupted as exc:
+        # Not a failure: the user asked it to stop and the checkpoint is intact. 130
+        # anyway, because to whatever ran us this is the same event as a Ctrl-C.
+        console.print(
+            f"[yellow]stopped[/yellow] — resume with "
+            f"[cyan]okf-loremaster build --resume {exc.run_id}[/cyan]"
+        )
+        raise typer.Exit(code=130) from exc
+    except (ConfigError, FileNotFoundError, ValueError) as exc:
+        # Escaped, because the fix these messages name is often an extra —
+        # `okf-loremaster[tui]` — and Rich reads the brackets as a markup tag and drops
+        # the one word the user needs to type.
+        console.print(f"[red]{escape(str(exc))}[/red]")
+        raise typer.Exit(code=1) from exc
+    except KeyboardInterrupt as exc:
+        # No id to offer: Ctrl-C can land before one is generated, and this handler
+        # cannot see it in any case. `runs` is where it can be looked up.
+        console.print(
+            "[yellow]interrupted[/yellow] — [cyan]okf-loremaster runs[/cyan] lists the "
+            "run id, then [cyan]build --resume <id>[/cyan] continues it"
+        )
+        raise typer.Exit(code=130) from exc
+
+
+def _report_outputs(directory: Path) -> None:
+    """Say where the deliverable is, and that moving it is one copy.
+
+    Printed rather than left to the reader because the whole point of the one-folder
+    layout is that it can be handed to a consumer without instructions, and a path that
+    is never shown is a path nobody knows to copy.
+    """
+    from okf_loremaster.okf.layout import okf_bundle_path, vector_store_path
+    from okf_loremaster.run import TRANSCRIPT_FILENAME
+
+    corpus = okf_bundle_path(directory)
+    store = vector_store_path(corpus)
+    console.print(f"\n[bold]output[/bold]  {directory}")
+    for label, path in (("okf", corpus), ("vectors", store)):
+        mark = "[green]+[/green]" if path.exists() else "[dim]-[/dim]"
+        console.print(f"  {mark} {label}/{'' if path.exists() else '  [dim]not kept[/dim]'}")
+    console.print(f"[dim]move it with[/dim]  [cyan]cp -r {directory} <somewhere>[/cyan]")
+    # Only `--tui` writes one: the plain renderer's output is already in the scrollback,
+    # where it can be selected. A full-screen app's is not, and it is gone the moment the
+    # alternate screen closes.
+    transcript = directory / TRANSCRIPT_FILENAME
+    if transcript.exists():
+        console.print(f"[dim]the run log, to paste[/dim]  [cyan]cat {transcript}[/cyan]")
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        # stdout, not stderr: `--version` output is meant to be piped.
+        typer.echo(f"{DISPLAY_NAME} {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        bool,
+        typer.Option("--version", callback=_version_callback, is_eager=True, help="Show version."),
+    ] = False,
+) -> None:
+    """Build and inspect Open Knowledge Format literature bundles."""
+
+
+def _env_template() -> tuple[str, str | None]:
+    """The annotated template `init` copies, and the name to report it by.
+
+    A checkout has `.env.example` at its root and that copy wins, because in a checkout it
+    is the file being edited. A `pip install` has no checkout, so the wheel carries the
+    same bytes as package data; without that fallback `init` writes nothing at all for
+    anyone who installed from PyPI. Never the user's own `.env` — only the template.
+    """
+    local = Path(".env.example")
+    if local.is_file():
+        return str(local), local.read_text(encoding="utf-8")
+    packaged = resources.files("okf_loremaster") / "env.example"
+    if packaged.is_file():
+        return "the packaged template", packaged.read_text(encoding="utf-8")
+    return str(local), None
+
+
+@app.command()
+def init(
+    force: Annotated[bool, typer.Option("--force", help="Overwrite an existing .env.")] = False,
+) -> None:
+    """Write a .env from the template and check the environment is usable."""
+    from rich.table import Table
+
+    from okf_loremaster.config import (
+        ENV_PREFIX,
+        ConfigError,
+        Role,
+        env_file_candidates,
+        load_settings,
+    )
+
+    target = Path(".env")
+    origin, template = _env_template()
+    if template is not None and (force or not target.exists()):
+        target.write_text(template, encoding="utf-8")
+        console.print(f"[green]wrote[/green] {target} from {origin} — fill it in, then rerun")
+    elif template is None and not target.exists():
+        console.print(f"[yellow]neither {origin} nor {target} found[/yellow]")
+
+    try:
+        settings = load_settings()
+    except ConfigError as exc:
+        console.print(f"[red]{escape(str(exc))}[/red]")
+        raise typer.Exit(code=1) from exc
+
+    found = [str(path) for path in env_file_candidates() if path.exists()]
+    table = Table.grid(padding=(0, 2))
+    table.add_column(justify="right", style="dim")
+    table.add_column()
+    table.add_row("env files", ", ".join(found) if found else "[yellow]none found[/yellow]")
+
+    missing = set(settings.missing_for_llm())
+    for role in Role:
+        name = f"{ENV_PREFIX}MODEL_{role.value.upper()}"
+        value = {
+            Role.FAST: settings.model_fast,
+            Role.BALANCED: settings.model_balanced,
+            Role.REASONING: settings.model_reasoning,
+        }[role]
+        table.add_row(role.value, value if value else f"[red]unset[/red] ({name})")
+
+    table.add_row(
+        "api key",
+        "[red]unset[/red] (ANTHROPIC_API_KEY)" if "ANTHROPIC_API_KEY" in missing else "set",
+    )
+    if settings.api_base:
+        table.add_row("api base", settings.api_base)
+    table.add_row(
+        "NCBI email",
+        settings.ncbi_email or f"[yellow]unset[/yellow] ({ENV_PREFIX}NCBI_EMAIL)",
+    )
+    table.add_row(
+        "NCBI key",
+        "set (10 req/s)" if settings.ncbi_api_key else "[dim]unset (3 req/s)[/dim]",
+    )
+    revision = settings.embed_revision or "[yellow]unpinned[/yellow]"
+    table.add_row("embeddings", f"{settings.embed_model} @ {revision}")
+    table.add_row("HF_HOME", str(settings.hf_home) if settings.hf_home else "[dim]default[/dim]")
+    table.add_row("cache dir", str(settings.cache_dir))
+    table.add_row("output dir", str(settings.output_dir))
+    console.print(table)
+
+    warning = settings.hf_home_warning()
+    if warning:
+        console.print(f"[yellow]![/yellow]  {warning}")
+
+    unpriced = settings.unpriced_roles()
+    if unpriced:
+        names = ", ".join(role.value for role in unpriced)
+        console.print(
+            f"[dim]note[/dim]  no price override for: {names}. If the provider is not in "
+            f"LiteLLM's price map, those calls report as 'cost unavailable' rather than a "
+            f"USD figure. Set {ENV_PREFIX}PRICE_<ROLE>_IN/_OUT to get one."
+        )
+
+    if missing:
+        console.print(f"[red]not ready[/red] — {len(missing)} required variable(s) unset")
+        raise typer.Exit(code=1)
+    console.print("[green]ready[/green]")
+
+
+@app.command(hidden=True)
+def selftest(
+    live: Annotated[
+        bool | None, typer.Option("--live/--no-live", help="Force or suppress the live meter.")
+    ] = None,
+    verbose: Annotated[int, typer.Option("-v", "--verbose", count=True)] = 0,
+) -> None:
+    """Exercise events, routing, retries, and cost accounting against a fake model."""
+    from okf_loremaster.selftest import run_selftest
+
+    code = asyncio.run(run_selftest(live=live, verbose=verbose, console=console))
+    raise typer.Exit(code=code)
+
+
+@app.command()
+def build(
+    # Optional only because `--resume` supplies it: a resumed run reads its question back
+    # out of the checkpoint, and asking for it again invites a retyped one that differs
+    # from the one the run was actually built on. Omitted without `--resume`, the run
+    # stops with a sentence saying so.
+    prompt: Annotated[
+        str | None,
+        typer.Argument(help="What you want to know. Not needed with --resume."),
+    ] = None,
+    charter: Annotated[
+        Path | None,
+        typer.Option(
+            "--charter",
+            help="Reuse a charter.yaml instead of drafting one. Skips the reasoning call.",
+            exists=True,
+            dir_okay=False,
+        ),
+    ] = None,
+    out: Annotated[
+        Path | None,
+        typer.Option("-o", "--out", help="Folder name, under the output directory."),
+    ] = None,
+    pool_size: Annotated[int, typer.Option(help="Candidate pool before screening.")] = 800,
+    screen_budget: Annotated[int, typer.Option(help="Max abstracts sent to the screener.")] = 400,
+    # Literals rather than the constants they mirror: importing them would pull pydantic
+    # into `--help`. `test_cli_defaults` fails if the two ever drift apart.
+    target_papers: Annotated[int, typer.Option(help="Target retained paper count.")] = 200,
+    topic_paper_min: Annotated[int, typer.Option(help="Minimum papers inside one topic.")] = 8,
+    topic_paper_max: Annotated[int, typer.Option(help="Maximum papers inside one topic.")] = 40,
+    max_topics: Annotated[
+        int, typer.Option(help="Topic folders the charter may divide the review into.", min=1)
+    ] = 8,
+    max_rounds: Annotated[
+        int, typer.Option(help="Search rounds, including the first. 1 disables re-query.", min=1)
+    ] = 2,
+    finalize: Annotated[
+        Finalize | None,
+        typer.Option(
+            "--finalize",
+            help="What to keep. Asked at the end if not given. `okf` skips embedding.",
+        ),
+    ] = None,
+    review: Annotated[bool, typer.Option("--review", help="Human sign-off before emit.")] = False,
+    interactive: Annotated[
+        bool,
+        typer.Option(
+            "--interactive", "-i", help="Stop at the charter and the pool, and ask before going on."
+        ),
+    ] = False,
+    dry_run: Annotated[
+        bool, typer.Option("--dry-run", help="Plan and cost the run. Makes zero LLM calls.")
+    ] = False,
+    resume: Annotated[
+        str | None,
+        typer.Option("--resume", help="Resume a run by id; `runs` lists them."),
+    ] = None,
+    tui: Annotated[bool, typer.Option("--tui", help="Full-screen Textual interface.")] = False,
+    json_out: Annotated[bool, typer.Option("--json", help="Emit machine-readable events.")] = False,
+    verbose: Annotated[int, typer.Option("-v", "--verbose", count=True, help="Verbosity.")] = 0,
+) -> None:
+    """Build a knowledge bundle from PubMed. This is the whole system."""
+    from okf_loremaster.curation import MAX_ROUNDS
+    from okf_loremaster.run import RunOptions, build_run, require_textual
+    from okf_loremaster.ui.plain import rich_enabled
+    from okf_loremaster.ui.summary import render_bundle, render_extraction, render_topics
+
+    if tui and json_out:
+        # Refused rather than degraded: a full-screen app writes escape sequences over
+        # the stream --json exists to keep parsable.
+        console.print(
+            "[red]--tui cannot be combined with --json[/red] — one paints a terminal, "
+            "the other feeds a program."
+        )
+        raise typer.Exit(code=1)
+    if finalize is not None and dry_run:
+        # A dry run writes nothing, so there is nothing to keep or discard.
+        console.print(
+            "[red]--finalize cannot be combined with --dry-run[/red] — a dry run "
+            "writes no bundle."
+        )
+        raise typer.Exit(code=1)
+    if review and (dry_run or json_out):
+        # Not a usability nicety. `--json` has nobody to ask and a dry run writes no
+        # bundle — signing under either would stamp `verified: human:<id>` on work no
+        # human looked at, which is the one claim in the format that has to be true.
+        # `--review` is independent of `--interactive`: signing off on a finished bundle
+        # and steering the search are different moments, and either can be wanted alone.
+        blocking = ", ".join(
+            flag for flag, on in (("--dry-run", dry_run), ("--json", json_out)) if on
+        )
+        console.print(
+            f"[red]--review cannot be combined with {blocking}[/red] — sign-off has to be "
+            "given by a person who saw the bundle."
+        )
+        raise typer.Exit(code=1)
+    if max_rounds > MAX_ROUNDS:
+        # A cap, not a preference. A third round re-screens a pool to ask the question
+        # the second one already failed to answer.
+        console.print(
+            f"[red]--max-rounds {max_rounds} exceeds the hard cap of {MAX_ROUNDS}[/red]"
+        )
+        raise typer.Exit(code=1)
+
+    # Declined rather than refused, because neither is the user asking for something
+    # incoherent. A dry run's deliverable *is* the printed plan, and a full-screen app
+    # takes the screen back when it closes; a terminal that cannot drive a live region
+    # cannot drive an app either.
+    if charter is not None and resume is not None:
+        # Refused rather than ranked. A resumed run replays from its checkpoint, where
+        # the charter node has already run and its answer is recorded, so a charter
+        # passed here would be read, reported in `--help` as doing something, and then
+        # quietly ignored. Silently disregarding a file the user named is worse than
+        # stopping.
+        console.print(
+            "[red]--charter cannot be combined with --resume[/red] — a resumed run "
+            "replays the charter it was built with. Start a fresh run to use another."
+        )
+        raise typer.Exit(code=1)
+
+    full_screen = tui
+    if tui and dry_run:
+        console.print("[dim]note[/dim]  --dry-run prints its plan, so --tui is not used here.")
+        full_screen = False
+    elif tui and not rich_enabled():
+        console.print("[dim]note[/dim]  no terminal to drive — falling back from --tui.")
+        full_screen = False
+    if full_screen:
+        # Before the screen is cleared, so a missing extra is readable.
+        with _reported():
+            require_textual()
+
+    options = RunOptions(
+        prompt=prompt or "",
+        charter_path=charter,
+        out=out,
+        pool_size=pool_size,
+        screen_budget=screen_budget,
+        target_papers=target_papers,
+        topic_paper_min=topic_paper_min,
+        topic_paper_max=topic_paper_max,
+        max_topics=max_topics,
+        max_rounds=max_rounds,
+        interactive=interactive,
+        review=review,
+        finalize=finalize,
+        dry_run=dry_run,
+        resume=resume,
+        tui=full_screen,
+        json_out=json_out,
+        verbose=verbose,
+    )
+
+    with _reported():
+        if full_screen:
+            from okf_loremaster.ui.tui import build_run_tui
+
+            state, directory = asyncio.run(build_run_tui(options))
+        else:
+            state, directory = asyncio.run(build_run(options, console=console))
+
+    if json_out:
+        return
+    render_topics(console, state)
+    render_extraction(console, state)
+    render_bundle(console, state)
+    _report_outputs(directory)
+    if not state.get("pool"):
+        raise typer.Exit(code=1)
+    # A bundle that failed the gate is still on disk and still worth reading; the exit
+    # code is what says so to whatever ran us.
+    if state.get("bundle") and not state.get("validated"):
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def runs(
+    limit: Annotated[int, typer.Option("-n", "--limit", help="How many to show.", min=1)] = 10,
+) -> None:
+    """List recent runs and how far each one got, with the id to resume it by."""
+    from rich.table import Table
+
+    from okf_loremaster.config import load_settings
+    from okf_loremaster.retention import (
+        MB,
+        directory_bytes,
+        extraction_cache_path,
+        http_cache_path,
+    )
+    from okf_loremaster.run import list_runs, store_size
+
+    with _reported():
+        settings = load_settings()
+        past = asyncio.run(list_runs(settings, limit=limit))
+        held = store_size(settings)
+        http = directory_bytes(http_cache_path(settings))
+        read = directory_bytes(extraction_cache_path(settings))
+
+    if not past:
+        console.print(
+            f"[dim]no runs in[/dim] {settings.cache_dir}\n"
+            f"[dim]start one with[/dim]  [cyan]okf-loremaster build \"your question\"[/cyan]"
+        )
+        return
+
+    table = Table(box=None, pad_edge=False, header_style="dim")
+    table.add_column("run id")
+    table.add_column("started", style="dim")
+    table.add_column("reached")
+    # One row per run, clipped rather than wrapped: this is a list to pick an id out of,
+    # and a four-line paragraph per entry buries the ids it exists to show.
+    table.add_column("question", overflow="ellipsis", no_wrap=True, max_width=52)
+    for run in past:
+        done = run.finished
+        table.add_row(
+            f"[dim]{run.run_id}[/dim]" if done else run.run_id,
+            f"{run.started:%b %d %H:%M}" if run.started else "—",
+            "[green]finished[/green]" if done else f"[yellow]{run.reached}[/yellow]",
+            escape(run.prompt) or "[dim]—[/dim]",
+        )
+    console.print(table)
+
+    # Only the unfinished ones are worth resuming, and only the newest of those is worth
+    # spelling out — the point is to show the shape of the command, not to enumerate it.
+    unfinished = next((run for run in past if not run.finished), None)
+    if unfinished is not None:
+        console.print(
+            f"\n[dim]resume with[/dim]  "
+            f"[cyan]okf-loremaster build --resume {unfinished.run_id}[/cyan]"
+            f"  [dim](the question is read back from the run)[/dim]"
+        )
+
+    # What the caches cost, next to what bounds each of them. Nothing else in the tool
+    # ever mentions this, so without it the only way to find out where the disk went is
+    # to go looking in the cache directory — which is how it reached three gigabytes
+    # before anyone noticed. Each line is a measurement and its ceiling, so a store
+    # sitting at its limit is visible rather than inferred.
+    keep = settings.checkpoint_keep_runs
+    kept = f"newest {keep}" if keep > 0 else "all"
+    console.print(f"\n[dim]caches in[/dim] {settings.cache_dir}")
+    for label, size, cap, note in (
+        ("checkpoints", held, settings.checkpoint_max_mb, f"{kept} runs"),
+        ("responses", http, settings.http_cache_max_mb, f"{settings.http_cache_ttl_days}d"),
+        ("readings", read, settings.extraction_cache_max_mb, "no expiry"),
+    ):
+        ceiling = f"{cap:,} MB" if cap > 0 else "uncapped"
+        console.print(
+            f"  [dim]{label:<12}[/dim] {size / MB:>7,.0f} MB "
+            f"[dim]of {ceiling}, {note}[/dim]"
+        )
+
+if __name__ == "__main__":
+    app()

okf_loremaster/clients/__init__.py

@@ -0,0 +1,162 @@
+"""HTTP clients for the four data sources.
+
+E-utilities, BioC and PubTator are all `*.ncbi.nlm.nih.gov` and the rate limit is
+enforced **per IP across all of them**, so they share one `HttpClient` and therefore one
+token bucket. Giving each client its own limiter is the obvious design and it is wrong:
+three clients at 8 rps each is 24 rps from NCBI's point of view.
+
+iCite is a different host with its own budget, so it gets its own.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import httpx
+
+from okf_loremaster.clients._http import (
+    ICITE_RPS,
+    NCBI_CEILING_WITH_KEY,
+    NCBI_CEILING_WITHOUT_KEY,
+    NCBI_RPS_WITH_KEY,
+    NCBI_RPS_WITHOUT_KEY,
+    DiskCache,
+    HttpClient,
+    HttpStats,
+    RateLimiter,
+)
+from okf_loremaster.clients.bioc import BioCClient, BioCDocument, BioCSection
+from okf_loremaster.clients.eutils import (
+    Author,
+    ESearchResult,
+    EUtilsClient,
+    MeshTerm,
+    PubMedRecord,
+)
+from okf_loremaster.clients.icite import CitationMetrics, ICiteClient
+from okf_loremaster.clients.pubtator import (
+    AnnotatedDocument,
+    Annotation,
+    PubTatorClient,
+)
+from okf_loremaster.config import ConfigError, Settings
+from okf_loremaster.events import EventBus
+from okf_loremaster.retention import http_cache_path
+
+__all__ = [
+    "AnnotatedDocument",
+    "Annotation",
+    "Author",
+    "BioCClient",
+    "BioCDocument",
+    "BioCSection",
+    "CitationMetrics",
+    "Clients",
+    "DiskCache",
+    "ESearchResult",
+    "EUtilsClient",
+    "HttpClient",
+    "HttpStats",
+    "ICiteClient",
+    "MeshTerm",
+    "PubMedRecord",
+    "PubTatorClient",
+    "RateLimiter",
+    "build_clients",
+    "ncbi_rate",
+]
+
+
+def ncbi_rate(settings: Settings) -> float:
+    """Requests per second to allow against NCBI, given whether a key is configured."""
+    has_key = bool(settings.ncbi_api_key)
+    rate = NCBI_RPS_WITH_KEY if has_key else NCBI_RPS_WITHOUT_KEY
+    ceiling = NCBI_CEILING_WITH_KEY if has_key else NCBI_CEILING_WITHOUT_KEY
+    return min(rate, ceiling)
+
+
+@dataclass
+class Clients:
+    """Every data source, sharing the right limiters."""
+
+    eutils: EUtilsClient
+    bioc: BioCClient
+    pubtator: PubTatorClient
+    icite: ICiteClient
+    ncbi_http: HttpClient
+    icite_http: HttpClient
+    # Both clients share it, and a run sweeps it. Held here rather than reached for
+    # through one of them, since it belongs to neither.
+    cache: DiskCache
+
+    @property
+    def stats(self) -> HttpStats:
+        """Combined counters across both hosts."""
+        a, b = self.ncbi_http.stats, self.icite_http.stats
+        return HttpStats(
+            requests=a.requests + b.requests,
+            cache_hits=a.cache_hits + b.cache_hits,
+            retries=a.retries + b.retries,
+            bytes_downloaded=a.bytes_downloaded + b.bytes_downloaded,
+        )
+
+    async def aclose(self) -> None:
+        await self.ncbi_http.aclose()
+        await self.icite_http.aclose()
+
+
+def build_clients(
+    settings: Settings,
+    *,
+    bus: EventBus | None = None,
+    transport: httpx.AsyncBaseTransport | None = None,
+    require_email: bool = True,
+) -> Clients:
+    """Wire all four clients.
+
+    `transport` is how a cassette gets injected: it sits below the cache and the
+    limiter, so replayed tests run the same code path as a live call.
+    """
+    if require_email and not settings.ncbi_email:
+        raise ConfigError(
+            "NCBI requires a contact address on every request and throttles traffic "
+            "that omits it. Set OKF_LOREMASTER_NCBI_EMAIL in your .env."
+        )
+
+    cache = DiskCache(
+        http_cache_path(settings),
+        ttl_days=settings.http_cache_ttl_days,
+        enabled=settings.http_cache_enabled,
+    )
+    user_agent = f"{settings.ncbi_tool} (mailto:{settings.ncbi_email or 'unset'})"
+
+    if settings.ca_bundle is not None and not settings.ca_bundle.is_file():
+        raise ConfigError(
+            f"OKF_LOREMASTER_CA_BUNDLE points at {settings.ca_bundle}, which is not a "
+            "file. Leave it unset to use the default trust store."
+        )
+
+    def make(rate: float) -> HttpClient:
+        return HttpClient(
+            limiter=RateLimiter(rate),
+            cache=cache,
+            transport=transport,
+            bus=bus,
+            timeout=settings.http_timeout,
+            max_retries=settings.http_max_retries,
+            user_agent=user_agent,
+            ca_bundle=settings.ca_bundle,
+        )
+
+    ncbi_http = make(ncbi_rate(settings))
+    icite_http = make(ICITE_RPS)
+
+    return Clients(
+        eutils=EUtilsClient(ncbi_http, settings),
+        bioc=BioCClient(ncbi_http),
+        pubtator=PubTatorClient(ncbi_http),
+        icite=ICiteClient(icite_http),
+        ncbi_http=ncbi_http,
+        icite_http=icite_http,
+        cache=cache,
+    )