puremethod 0.1.0__py3-none-any.whl

app/api/run_routes.py

@@ -0,0 +1,311 @@
+"""Runs, commands, ledger reads, live events and downloads (08-app.md §3, KB-021).
+
+Control endpoints only queue commands; the run's worker applies them through `loop`
+(§5 step 2). Everything shown comes from the ledger or `loop.status` (INV-7)."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import time
+from collections.abc import Callable, Iterator
+from dataclasses import asdict
+from datetime import UTC, datetime
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Depends, Query, Request
+from fastapi.responses import FileResponse, Response, StreamingResponse
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+from starlette.background import BackgroundTask
+
+from app import executor_config, model_endpoints
+from app.api import links
+from app.api.common import Ctx, clean_errors, ctx, not_found, repo, tenant, unprocessable
+from app.outputs import bundle_ref
+from app.repo import RunRow, TenantRepo
+from app.setup import run_services, setup_status
+from app.statuses import TERMINAL
+from ledger import ArtifactMissing, Entry
+from loop import RunConfig
+
+router = APIRouter()
+Tenant = Annotated[str, Depends(tenant)]
+DIGEST = re.compile(r"^sha256:[0-9a-f]{64}$")  # the ledger's digest form (04-ledger.md §4)
+MAX_ENTRIES = 5000
+
+
+class _In(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class RunIn(_In):
+    title: Annotated[str, Field(max_length=200)] = ""
+    config: dict[str, Any]
+
+
+class PauseIn(_In):
+    reason: Annotated[str, Field(max_length=500)] = ""
+
+
+class Empty(_In):
+    pass
+
+
+class CheckpointIn(_In):
+    decision: dict[str, Any]
+
+
+def _run(r: TenantRepo, run_id: str) -> RunRow:
+    run = r.get_run(run_id)
+    if run is None:
+        not_found()
+    return run
+
+
+def _status(c: Ctx, run: RunRow) -> dict[str, Any] | None:
+    return asdict(c.status.status(run.ledger_run_id)) if run.ledger_run_id else None
+
+
+def _view(c: Ctx, run: RunRow) -> dict[str, Any]:
+    view: dict[str, Any] = {
+        "id": run.id, "title": run.title, "created_at": run.created_at, "state": run.state,
+        "start_error": run.start_error, "worker_error": run.worker_error, "status": None,
+        "status_error": None}
+    try:
+        view["status"] = _status(c, run)
+    except Exception as exc:  # one unreadable run must not break the list (review finding 5)
+        view["status_error"] = f"status unavailable: {type(exc).__name__}"
+    return view
+
+
+# ---- runs ----------------------------------------------------------------------------------
+
+@router.post("/runs", status_code=202)
+def create_run(request: Request, tid: Tenant, body: RunIn) -> dict[str, Any]:
+    """Expands the LLM profile, which must be checked (KB-041), checks every executor, profile
+    and credential named belongs to the tenant, validates the `RunConfig`, and queues `start`
+    (KB-021). Consents come only from this request; nothing is carried over from earlier runs
+    (INV-4)."""
+    c, r = ctx(request), repo(request, tid)
+    setup = setup_status(r, request.app.state.local_status)
+    if not setup.complete:  # 08 §5 step 13
+        unprocessable("finish setup first: " + "; ".join(setup.missing))
+    cfg = dict(body.config)
+    if "llm" in cfg:
+        unprocessable("llm is set from llm_profile")
+    profile = r.get_profile(str(cfg.pop("llm_profile", "")))
+    if profile is None:
+        unprocessable("unknown llm_profile")
+    if not r.profile_checked(profile):  # 08 §3 Run request (KB-041)
+        unprocessable(f"check the LLM profile {profile.name!r} first: its latest check did not "
+                      "pass, or it changed after that check")
+    # Endpoints become what the worker needs: a URL, or a tunnel to an SSH machine with its
+    # resolved connection, snapshotted like the executor (07 §4, KB-036).
+    try:
+        cfg["llm"] = {role: model_endpoints.expand(spec, c.settings.mode, r.resolve_machine)
+                      for role, spec in profile.roles.items()}
+    except KeyError as exc:
+        unprocessable(f"the profile names an SSH machine that no longer exists: {exc}")
+    except ValueError as exc:
+        unprocessable(f"the profile's SSH machine cannot be reached: {exc}")
+    executor = cfg.get("executor")
+    row = r.get_executor(str(executor.get("id", ""))) if isinstance(executor, dict) else None
+    if row is None:
+        unprocessable("unknown executor")
+    try:
+        executor_config.validate(row.kind, row.config, c.settings.mode)
+        config = RunConfig.model_validate(cfg)
+    except ValidationError as exc:
+        unprocessable(json.dumps(clean_errors(exc.errors())))
+    except ValueError as exc:
+        unprocessable(str(exc))
+    stored = set(r.credential_types())
+    needed = set(config.credential_names()) | set(
+        executor_config.credentials_named(row.kind, row.config)) | set(
+        model_endpoints.ssh_credentials(config.llm))
+    for name in sorted(needed - stored):
+        unprocessable(f"credential {name!r} is not stored")
+    services = run_services(r, c.settings.purescholar_url, c.settings.puretrace_url)
+    run, cmd = r.create_run(body.title.strip() or config.idea[:80],
+                            config.model_dump(mode="json"), profile.prices, row, services,
+                            llm_profile_id=profile.id)
+    return {"run_id": run.id, "command_id": cmd.id}
+
+
+@router.get("/runs")
+def list_runs(request: Request, tid: Tenant) -> list[dict[str, Any]]:
+    c = ctx(request)
+    return [_view(c, run) for run in repo(request, tid).list_runs()]
+
+
+@router.get("/runs/{run_id}")
+def get_run(request: Request, tid: Tenant, run_id: str) -> dict[str, Any]:
+    return _view(ctx(request), _run(repo(request, tid), run_id))
+
+
+def _queue(request: Request, tid: str, run_id: str, kind: str,
+           payload: dict[str, Any]) -> dict[str, Any]:
+    r = repo(request, tid)
+    run = _run(r, run_id)
+    if run.state == "start_failed":
+        unprocessable("the run did not start")
+    return {"command_id": r.add_command(run.id, kind, payload).id}
+
+
+@router.post("/runs/{run_id}/pause", status_code=202)
+def pause(request: Request, tid: Tenant, run_id: str, body: PauseIn) -> dict[str, Any]:
+    return _queue(request, tid, run_id, "pause", {"reason": body.reason})
+
+
+@router.post("/runs/{run_id}/resume", status_code=202)
+def resume(request: Request, tid: Tenant, run_id: str, body: Empty) -> dict[str, Any]:
+    return _queue(request, tid, run_id, "resume", {})
+
+
+@router.post("/runs/{run_id}/stop", status_code=202)
+def stop(request: Request, tid: Tenant, run_id: str, body: Empty) -> dict[str, Any]:
+    return _queue(request, tid, run_id, "stop", {})
+
+
+@router.post("/runs/{run_id}/checkpoints/{checkpoint_id}", status_code=202)
+def decide(request: Request, tid: Tenant, run_id: str, checkpoint_id: str,
+           body: CheckpointIn) -> dict[str, Any]:
+    return _queue(request, tid, run_id, "checkpoint",
+                  {"checkpoint_id": checkpoint_id, "decision": body.decision})
+
+
+@router.get("/runs/{run_id}/commands/{command_id}")
+def get_command(request: Request, tid: Tenant, run_id: str, command_id: str) -> dict[str, Any]:
+    cmd = repo(request, tid).get_command(run_id, command_id)
+    if cmd is None:
+        not_found()
+    return {"id": cmd.id, "kind": cmd.kind, "state": cmd.state, "reason": cmd.reason,
+            "created_at": cmd.created_at, "done_at": cmd.done_at}
+
+
+# ---- ledger reads --------------------------------------------------------------------------
+
+@router.get("/runs/{run_id}/entries")
+def entries(request: Request, tid: Tenant, run_id: str,
+            since_seq: Annotated[int, Query(ge=0)] = 0,
+            types: Annotated[str, Query(max_length=1000)] = "",
+            limit: Annotated[int, Query(ge=1, le=MAX_ENTRIES)] = 1000) -> dict[str, Any]:
+    c, run = ctx(request), _run(repo(request, tid), run_id)
+    if run.ledger_run_id is None:
+        return {"entries": []}
+    wanted = [t for t in types.split(",") if t] or None
+    out: list[dict[str, Any]] = []
+    for e in c.ledger.entries(run.ledger_run_id, types=wanted, since_seq=since_seq):
+        out.append(e.to_dict())
+        if len(out) >= limit:
+            break
+    return {"entries": out}
+
+
+@router.get("/runs/{run_id}/artifacts/{digest}")
+def artifact(request: Request, tid: Tenant, run_id: str, digest: str) -> Response:
+    c, run = ctx(request), _run(repo(request, tid), run_id)
+    if run.ledger_run_id is None or not DIGEST.match(digest):
+        not_found()
+    try:
+        data = c.ledger.get_artifact(run.ledger_run_id, digest)
+    except ArtifactMissing:
+        not_found()
+    # Agent-written content: never rendered by the browser.
+    name = digest.removeprefix("sha256:")
+    return Response(data, media_type="application/octet-stream",
+                    headers={"Content-Disposition": f'attachment; filename="{name}"',
+                             "X-Content-Type-Options": "nosniff"})
+
+
+# ---- live events (SSE) ---------------------------------------------------------------------
+
+def _sse(event: str, seq: int, data: Any) -> str:
+    return f"id: {seq}\nevent: {event}\ndata: {json.dumps(data, separators=(',', ':'))}\n\n"
+
+
+def event_stream(c: Ctx, r: TenantRepo, run_id: str, since: int, *,
+                 clock: Callable[[], float] = time.monotonic,
+                 sleep: Callable[[float], None] = time.sleep) -> Iterator[str]:
+    """`entry` events in ledger order, then a `status` after each batch; ids are ledger
+    seqs, so `Last-Event-ID` resumes. Ends after the final status of a finished run."""
+    last, first, beat = since, True, clock()
+    while True:
+        run = r.get_run(run_id)
+        if run is None or run.state == "start_failed":
+            return
+        batch: list[Entry] = []
+        if run.ledger_run_id is not None:
+            batch = list(c.ledger.entries(run.ledger_run_id, since_seq=last))
+            for e in batch:
+                yield _sse("entry", e.seq, e.to_dict())
+                last = e.seq
+            if batch or first:
+                status = c.status.status(run.ledger_run_id)
+                yield _sse("status", last, asdict(status))
+                beat = clock()
+                if status.status in TERMINAL:
+                    return
+            first = False
+        if not batch and clock() - beat >= c.heartbeat_s:
+            yield ": keep-alive\n\n"
+            beat = clock()
+        sleep(c.events_poll_s)
+
+
+@router.get("/runs/{run_id}/events")
+def events(request: Request, tid: Tenant, run_id: str,
+           since: Annotated[int, Query(ge=0)] = 0) -> StreamingResponse:
+    r = repo(request, tid)
+    _run(r, run_id)
+    header = request.headers.get("last-event-id", "")
+    start = int(header) if header.isdigit() else since
+    return StreamingResponse(event_stream(ctx(request), r, run_id, start),
+                             media_type="text/event-stream",
+                             headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"})
+
+
+# ---- downloads (INV-6) ---------------------------------------------------------------------
+
+def _download(request: Request, tid: str, run_id: str, obj: str, exp: int | None,
+              sig: str | None) -> Response:
+    c = ctx(request)
+    run = _run(repo(request, tid), run_id)
+    lid = run.ledger_run_id
+    ref = bundle_ref(c.ledger, lid) if lid else None
+    if lid is None or ref is None or (obj == "paper" and c.outputs.paper(lid, ref) is None):
+        not_found()
+    now = time.time()
+    if exp is None or sig is None:
+        expires = int(now) + links.LINK_TTL_S
+        token = links.sign(c.link_key, tid, run.id, obj, expires)
+        return Response(json.dumps({
+            "url": f"/api/v1/runs/{run.id}/{obj}?exp={expires}&sig={token}",
+            "expires_at": datetime.fromtimestamp(expires, UTC).isoformat()}),
+            media_type="application/json")
+    if not links.valid(c.link_key, tid, run.id, obj, exp, sig, now):
+        not_found()
+    if obj == "paper":
+        pdf = c.outputs.paper(lid, ref)
+        if pdf is None:
+            not_found()
+        return FileResponse(pdf, media_type="application/pdf", filename=f"{run.id}-paper.pdf")
+    archive = c.outputs.bundle_archive(lid, ref, run.id)
+    if archive is None:
+        not_found()
+    return FileResponse(archive, media_type="application/gzip",
+                        filename=f"{run.id}-bundle.tar.gz",
+                        background=BackgroundTask(os.unlink, archive))
+
+
+@router.get("/runs/{run_id}/paper", response_model=None)
+def paper(request: Request, tid: Tenant, run_id: str, exp: int | None = None,
+          sig: Annotated[str | None, Query(max_length=128)] = None) -> Response:
+    return _download(request, tid, run_id, "paper", exp, sig)
+
+
+@router.get("/runs/{run_id}/bundle", response_model=None)
+def bundle(request: Request, tid: Tenant, run_id: str, exp: int | None = None,
+           sig: Annotated[str | None, Query(max_length=128)] = None) -> Response:
+    return _download(request, tid, run_id, "bundle", exp, sig)

app/api/setup_routes.py

@@ -0,0 +1,267 @@
+"""Onboarding (08-app.md §3, §5 steps 13 and 14, KB-025, KB-029): credential checks, the
+literature and PureTrace settings, and the setup status. Checks only queue work; a worker
+decrypts the one credential checked (INV-2)."""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+from typing import Annotated, Any, Literal
+from urllib.parse import urlsplit
+
+from fastapi import APIRouter, Depends, Request
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from app import bundled, literature_sources, model_endpoints
+from app.api.common import active_runs, ctx, not_found, repo, tenant, unprocessable
+from app.setup import PURESCHOLAR_CREDENTIAL, literature_status, setup_status
+
+router = APIRouter()
+Tenant = Annotated[str, Depends(tenant)]
+LLM_PROVIDERS = ("anthropic", "openai", "openai_compatible")
+EMBEDDINGS = ("local", "openai", "sentence-transformers")
+
+
+class _In(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+def _http_url(value: str) -> str:
+    parts = urlsplit(value)
+    if parts.scheme not in ("http", "https") or not parts.netloc:
+        raise ValueError("an http or https URL")
+    return value.rstrip("/")
+
+
+class Price(_In):
+    input: Annotated[float, Field(ge=0)]
+    output: Annotated[float, Field(ge=0)]
+
+
+class CheckIn(_In):
+    """LLM key: provider and model (base URL, price optional). Service key: url."""
+    provider: Literal["anthropic", "openai", "openai_compatible"] | None = None
+    model: Annotated[str, Field(min_length=1, max_length=200)] | None = None
+    base_url: str | None = None
+    allow_unencrypted: bool = False  # INV-12: plain http to a public address, confirmed
+    local_port: Annotated[int, Field(ge=1, le=65535)] | None = None  # a model on this computer
+    machine: str | None = None  # a model on an SSH machine (KB-036)
+    remote_port: Annotated[int, Field(ge=1, le=65535)] | None = None
+    price: Price | None = None
+    url: str | None = None
+    source: Literal["semanticscholar", "ieee", "elsevier", "springer"] | None = None  # KB-039
+
+    @field_validator("base_url", "url")
+    @classmethod
+    def _url(cls, v: str | None) -> str | None:
+        return None if v is None else _http_url(v)
+
+
+class LiteratureIn(_In):
+    mode: Literal["local", "remote"]
+    url: str | None = None  # remote
+    embedding: Literal["local", "openai", "sentence-transformers"] | None = None  # local
+    llm_credential: str | None = None  # local: the LLM key PureScholar generates with, or
+    llm_profile: str | None = None  # a profile role's model (KB-038)
+    llm_role: Literal["planner", "coder", "analyst"] | None = None
+    openai_credential: str | None = None  # local, embedding "openai"
+    # local: the scholarly sources, their keys by key group, the OpenAlex email (KB-039)
+    sources: list[str] | None = None
+    source_keys: dict[str, str] | None = None
+    openalex_email: Annotated[str, Field(max_length=254)] | None = None
+
+    @field_validator("url")
+    @classmethod
+    def _url(cls, v: str | None) -> str | None:
+        return None if v is None else _http_url(v)
+
+
+class PureTraceIn(_In):
+    url: str | None = None
+
+    @field_validator("url")
+    @classmethod
+    def _url(cls, v: str | None) -> str | None:
+        return None if v is None else _http_url(v)
+
+
+# ---- credential checks -----------------------------------------------------------------------
+
+@router.post("/credentials/{credential_id}/check", status_code=202)
+def start_credential_check(request: Request, tid: Tenant, credential_id: str,
+                           body: CheckIn) -> dict[str, Any]:
+    r = repo(request, tid)
+    cred = r.credential(credential_id)
+    if cred is None:
+        not_found()
+    if cred.type == "llm-key":
+        if body.provider is None or body.model is None or body.url is not None:
+            unprocessable("an LLM key check names provider and model")
+        mode = ctx(request).settings.mode
+        # The endpoint, as a profile role would name it (07 §4, KB-036): the check of a
+        # local or SSH endpoint is what lets the bundled PureScholar use it (08 §5 step 12).
+        spec = {k: v for k, v in {"provider": body.provider, "base_url": body.base_url,
+                                  "local_port": body.local_port, "machine": body.machine,
+                                  "remote_port": body.remote_port,
+                                  "allow_unencrypted": body.allow_unencrypted or None}.items()
+                if v is not None}
+        try:  # 08 INV-11, INV-12 (KB-036)
+            model_endpoints.check(spec, mode, {m.id for m in r.list_machines()})
+        except model_endpoints.EndpointRefused as exc:
+            unprocessable(str(exc))
+        try:
+            expanded = model_endpoints.expand(spec, mode, r.resolve_machine)
+        except (KeyError, ValueError) as exc:
+            unprocessable(f"the SSH machine cannot be used: {exc}")
+        req: dict[str, Any] = {"provider": body.provider, "model": body.model}
+        for key in ("base_url", "public_only", "ssh"):
+            if key in expanded:
+                req[key] = expanded[key]
+        if body.local_port is not None:
+            req["local_port"] = body.local_port
+        if body.price:
+            req["price"] = body.price.model_dump()
+    elif cred.type in ("purescholar-key", "puretrace-key"):
+        llm_fields = (body.provider, body.model, body.base_url, body.price, body.local_port,
+                      body.machine, body.remote_port, body.source)
+        if body.url is None or any(v is not None for v in llm_fields):
+            unprocessable("a service key check names url only")
+        req = {"url": body.url}
+    elif cred.type == literature_sources.CREDENTIAL_TYPE:
+        others = (body.provider, body.model, body.base_url, body.price, body.local_port,
+                  body.machine, body.remote_port, body.url)
+        if body.source is None or any(v is not None for v in others):
+            unprocessable("a literature-source key check names source only")
+        req = {"group": body.source}
+    else:
+        unprocessable(f"a {cred.type} credential cannot be checked")
+    check = r.add_credential_check(cred.id, req)
+    return {"check_id": check.id, "state": check.state}
+
+
+@router.get("/credentials/{credential_id}/check/{credential_check_id}")
+def get_credential_check(request: Request, tid: Tenant, credential_id: str,
+                         credential_check_id: str) -> dict[str, Any]:
+    check = repo(request, tid).get_credential_check(credential_id, credential_check_id)
+    if check is None:
+        not_found()
+    return asdict(check)
+
+
+# ---- service settings ------------------------------------------------------------------------
+
+@router.get("/services/literature")
+def get_literature(request: Request, tid: Tenant) -> dict[str, Any]:
+    r = repo(request, tid)
+    status = literature_status(r, request.app.state.local_status)
+    return {"setting": r.service_setting("literature"),
+            "status": {"state": status.state, "reason": status.reason}}
+
+
+@router.put("/services/literature")
+def put_literature(request: Request, tid: Tenant, body: LiteratureIn) -> dict[str, Any]:
+    r = repo(request, tid)
+    types = r.credential_types()
+    config: dict[str, Any]
+    if body.mode == "remote":
+        if body.url is None or any(v is not None for v in (
+                body.embedding, body.llm_credential, body.openai_credential, body.llm_profile,
+                body.llm_role, body.sources, body.source_keys, body.openalex_email)):
+            unprocessable("remote mode names url only")
+        if types.get(PURESCHOLAR_CREDENTIAL) != "purescholar-key":
+            unprocessable(f"store the PureScholar key as {PURESCHOLAR_CREDENTIAL!r} first")
+        config = {"mode": "remote", "url": body.url}
+    else:
+        by_profile = body.llm_profile is not None
+        one_model = (body.llm_credential is None) == by_profile  # exactly one of the two
+        if body.url is not None or body.embedding is None or not one_model or \
+                by_profile != (body.llm_role is not None):
+            unprocessable("local mode names embedding, and llm_credential or llm_profile with "
+                          "llm_role")
+        if PURESCHOLAR_CREDENTIAL in (body.llm_credential, body.openai_credential):
+            # The bundled PureScholar's own key is stored under this name (08 §5 step 12).
+            unprocessable(f"{PURESCHOLAR_CREDENTIAL!r} is the PureScholar key's name; store "
+                          "the model key under another name")
+        if by_profile:
+            profile = r.get_profile(str(body.llm_profile))
+            if profile is None or str(body.llm_role) not in profile.roles:
+                unprocessable(f"no LLM profile {body.llm_profile!r} with that role")
+        elif types.get(str(body.llm_credential)) != "llm-key":
+            unprocessable(f"no llm-key credential named {body.llm_credential!r}")
+        if body.embedding == "openai" and types.get(body.openai_credential or "") != "llm-key":
+            unprocessable("the openai embedding needs openai_credential, an llm-key")
+        if body.embedding != "openai" and body.openai_credential is not None:
+            unprocessable("openai_credential is only for the openai embedding")
+        config = {"mode": "local", "embedding": body.embedding}
+        if by_profile:
+            config |= {"llm_profile": body.llm_profile, "llm_role": body.llm_role}
+        else:
+            config["llm_credential"] = body.llm_credential
+        if body.openai_credential:
+            config["openai_credential"] = body.openai_credential
+        # The scholarly sources (KB-039): defaults when not named, as for a setting saved
+        # before them.
+        sources = body.sources if body.sources is not None \
+            else list(literature_sources.DEFAULT_SOURCES)
+        source_keys = {k: v for k, v in (body.source_keys or {}).items() if v}
+        email = (body.openalex_email or "").strip()
+        try:
+            literature_sources.validate(sources, source_keys, email, types)
+        except literature_sources.SourcesRefused as exc:
+            unprocessable(str(exc))
+        config["sources"] = sources
+        if source_keys:
+            config["source_keys"] = source_keys
+        if email:
+            config["openalex_email"] = email
+    old = r.service_setting("literature") or {}
+    # 08 §5 step 12 (KB-032): local to remote stops the bundled service; remote to local makes
+    # the bundled start replace the `purescholar` key a remote run authenticates with; any
+    # local save restarts the bundled service. None of these happens under an active run. A
+    # remote URL change is allowed: a run keeps the URL it was created with.
+    if old and not (old.get("mode") == config["mode"] == "remote"):
+        active = active_runs(request, r)
+        if active:
+            names = ", ".join(f"{run.title!r} ({run.id})" for run in active)
+            unprocessable("the literature service cannot change while runs are active: "
+                          f"{names}; wait for them to finish or stop them")
+    # The embedding the bundled corpus was indexed with survives a switch to remote mode,
+    # since the corpus stays in its volume (review of slice 3, MINOR-2).
+    indexed = old.get("embedding") if old.get("mode") == "local" else old.get("local_embedding")
+    if config["mode"] == "local" and indexed and indexed != config["embedding"] \
+            and request.query_params.get("reindex") != "yes":
+        # 08 §5 step 12: a new embedding needs a re-index; say so before applying it.
+        unprocessable("changing the embedding re-indexes the stored papers; "
+                      "send ?reindex=yes to confirm")
+    if config["mode"] == "remote" and indexed:
+        config["local_embedding"] = indexed
+    r.set_service_setting("literature", config)
+    if config["mode"] == "local":
+        bundled.request_start(r)  # the supervisor starts it (08 §5 step 12)
+    elif old.get("mode") == "local":
+        bundled.stop_tenant(r, "the literature service is remote")
+    if config["mode"] == "remote":
+        cred = next((c for c in r.list_credentials() if c.name == PURESCHOLAR_CREDENTIAL), None)
+        if cred is None:  # deleted meanwhile
+            unprocessable(f"store the PureScholar key as {PURESCHOLAR_CREDENTIAL!r} first")
+        r.add_credential_check(cred.id, {"url": config["url"]})
+    return get_literature(request, tid)
+
+
+@router.get("/services/puretrace")
+def get_puretrace(request: Request, tid: Tenant) -> dict[str, Any]:
+    setting = repo(request, tid).service_setting("puretrace")
+    return {"url": setting.get("url") if setting else None}
+
+
+@router.put("/services/puretrace")
+def put_puretrace(request: Request, tid: Tenant, body: PureTraceIn) -> dict[str, Any]:
+    repo(request, tid).set_service_setting("puretrace",
+                                           {"url": body.url} if body.url else None)
+    return get_puretrace(request, tid)
+
+
+# ---- setup -----------------------------------------------------------------------------------
+
+@router.get("/setup")
+def get_setup(request: Request, tid: Tenant) -> dict[str, Any]:
+    return setup_status(repo(request, tid), request.app.state.local_status).as_dict()