thisness 0.1.0__py3-none-any.whl

thisness/__init__.py

@@ -0,0 +1,13 @@
+"""Thisness: identity resolution for imperfect observations."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from thisness.engine import ObservationOutcome, RunResult, Thisness
+from thisness.ids import IdFactory
+
+try:
+    __version__ = version("thisness")
+except PackageNotFoundError:  # running from a source tree without an install
+    __version__ = "0.0.0"
+
+__all__ = ["IdFactory", "ObservationOutcome", "RunResult", "Thisness", "__version__"]

thisness/_canonical.py

@@ -0,0 +1,41 @@
+"""Canonical JSON and content digests.
+
+Fingerprints and component config hashes must not depend on dict key order or
+on how a value was spelled in Python. Sets are rejected because their order is
+not defined.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from datetime import date, datetime
+from typing import Any
+
+
+def _default(value: Any) -> Any:
+    if isinstance(value, datetime):
+        if value.tzinfo is None:
+            raise TypeError("naive datetimes are ambiguous; use timezone-aware datetimes")
+        return value.isoformat()
+    if isinstance(value, date):
+        return value.isoformat()
+    if isinstance(value, (set, frozenset)):
+        raise TypeError("sets have no defined order; use a sorted list")
+    raise TypeError(f"{type(value).__name__} is not JSON-serializable")
+
+
+def canonical_json(value: Any) -> str:
+    return json.dumps(
+        value,
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+        allow_nan=False,
+        default=_default,
+    )
+
+
+def digest(value: Any) -> str:
+    """SHA-256 hex digest of the canonical JSON of ``value``."""
+    return hashlib.sha256(canonical_json(value).encode("utf-8")).hexdigest()

thisness/adjudicate.py

@@ -0,0 +1,173 @@
+"""The LLM adjudicator (design 05 §4, PRD appendix A.7).
+
+A model judges the node pairs a run's Fellegi-Sunter edge policy left contested, as
+one more pair resolver in its own family. It is given each pair's two records,
+filtered by the profile's privacy policy, and the comparison results behind the
+pair, each with an id it must cite. Answers that cite ids they were not given, or
+name a relation the profile does not offer, are discarded.
+
+In ``shadow`` mode answers are recorded and change nothing. In ``decide`` mode a
+``same`` answer makes the edge strong when the Fellegi-Sunter weight is at least
+``floor_bits``, and a ``different`` answer makes it negative; consensus, holdout
+and the blast-radius policy then apply exactly as they do to any edge.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field, replace
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+from thisness.core.components import ComponentRef
+from thisness.llm.client import Answer, BudgetExhausted, LLMClient
+from thisness.llm.privacy import filter_attributes
+from thisness.llm.prompts import Prompt
+
+Decision = Literal["same", "different", "related", "unsure"]
+ReasonCode = Literal[
+    "NAME_EQUIVALENT", "NAME_TYPO", "ABBREVIATION_OR_ACRONYM", "LEGAL_FORM_ONLY",
+    "NICKNAME_OR_TRANSLITERATION", "SHARED_IDENTIFIER", "CONFLICTING_IDENTIFIER",
+    "SHARED_CONTACT", "SAME_LOCATION", "DIFFERENT_LOCATION", "DIFFERENT_DESCRIPTOR",
+    "COMMON_NAME", "SHARED_HOUSEHOLD", "DIFFERENT_BIRTH_DATE", "GROUP_OR_PARENT",
+    "INSUFFICIENT_EVIDENCE", "OTHER",
+]  # fmt: skip
+
+
+class PairAnswer(BaseModel):
+    pair: str
+    decision: Decision
+    relation: str | None = None
+    supporting: list[str] = Field(default_factory=list)
+    contradicting: list[str] = Field(default_factory=list)
+    reason_codes: list[ReasonCode] = Field(default_factory=list)
+    rationale: str | None = Field(default=None, max_length=600)
+
+
+class AdjudicationAnswer(BaseModel):
+    answers: list[PairAnswer]
+
+
+def default_prompt() -> Prompt:
+    return Prompt.load("adjudicate_pairs", "2", AdjudicationAnswer)
+
+
+@dataclass(frozen=True)
+class PairCase:
+    """One contested node pair, as the adjudicator sees it."""
+
+    nodes: tuple[str, str]
+    records: tuple[dict[str, Any], dict[str, Any]]  # unfiltered; filtered on the way out
+    comparisons: tuple[dict[str, Any], ...]  # {"id", "comparison", "level", "bits"}
+    evidence_keys: Mapping[str, tuple[str, str, str]]  # local id -> (left, right, comparison)
+    weight: float  # the strongest Fellegi-Sunter weight behind the pair
+
+
+@dataclass(frozen=True)
+class Adjudication:
+    case: PairCase
+    answer: PairAnswer | None
+    invocation_id: str | None
+    status: str  # ok, invalid_citation, unknown_relation, missing, failed, skipped
+    applied: bool = False
+
+
+@dataclass
+class Adjudicator:
+    client: LLMClient
+    model: str = "claude-sonnet-5"
+    mode: Literal["shadow", "decide"] = "shadow"
+    floor_bits: float = 6.0
+    pairs_per_call: int = 8
+    max_pairs: int | None = 500
+    prompt: Prompt = field(default_factory=default_prompt)
+    # A model's "same" yields to a contradiction (design 06 §10.7): where the edges it
+    # set strong would put a negative or cannot-link pair inside one component, they go
+    # back to contested and the component is settled on the evidence alone. A wrong
+    # "same" then costs a review of that pair, not a hold on a whole taxon.
+    same_yields: bool = True
+
+    @property
+    def ref(self) -> ComponentRef:
+        config = {"model": self.model, "mode": self.mode, "floor_bits": self.floor_bits,
+                  "pairs_per_call": self.pairs_per_call, "prompt": self.prompt.ref.ref}  # fmt: skip
+        if not self.same_yields:  # the original policy keeps its original ref
+            return ComponentRef.of("resolver", "llm_adjudicator", "1", config)
+        return ComponentRef.of("resolver", "llm_adjudicator", "2", {**config, "same_yields": True})
+
+    def edge(self, adjudication: Adjudication) -> str | None:
+        """The edge class a decided answer sets, or None to leave the edge as it is."""
+        answer = adjudication.answer
+        if self.mode != "decide" or answer is None:
+            return None
+        if answer.decision == "same" and adjudication.case.weight >= self.floor_bits:
+            return "strong"
+        if answer.decision == "different":
+            return "negative"
+        return None
+
+    def for_profile(self, profile: Any) -> Adjudicator:
+        """This adjudicator with the profile's guidance in its prompt (design 06 §6)."""
+        prompt = self.prompt.for_profile(profile)
+        return self if prompt is self.prompt else replace(self, prompt=prompt)
+
+    def adjudicate(
+        self,
+        cases: Sequence[PairCase],
+        *,
+        entity_type: str,
+        attributes: Mapping[str, Any],
+        relations: Sequence[str],
+        run_id: str | None = None,
+        stage_id: str | None = None,
+    ) -> list[Adjudication]:
+        ordered = sorted(cases, key=lambda c: (-c.weight, c.nodes))
+        chosen = ordered if self.max_pairs is None else ordered[: self.max_pairs]
+        skipped = [Adjudication(c, None, None, "skipped") for c in ordered[len(chosen) :]]
+        batches = [chosen[i : i + self.pairs_per_call]
+                   for i in range(0, len(chosen), self.pairs_per_call)]  # fmt: skip
+        local = self.client.provider.local
+
+        def payload(batch: Sequence[PairCase]) -> dict[str, Any]:
+            pairs = []
+            for i, case in enumerate(batch):
+                a, b = (dict(zip(("fields", "withheld"),
+                                 filter_attributes(r, attributes, local=local), strict=True))
+                        for r in case.records)  # fmt: skip
+                pairs.append({"pair": f"P{i + 1}", "a": {"ref": case.nodes[0], **a},
+                              "b": {"ref": case.nodes[1], **b},
+                              "comparisons": list(case.comparisons)})  # fmt: skip
+            return {"entity_type": entity_type, "relations": list(relations), "pairs": pairs}
+
+        def run(batch: Sequence[PairCase]) -> list[Adjudication]:
+            try:
+                result: Answer = self.client.call(self.prompt, model=self.model,
+                                                  payload=payload(batch), run_id=run_id,
+                                                  stage_id=stage_id)  # fmt: skip
+            except BudgetExhausted:
+                return [Adjudication(c, None, None, "skipped") for c in batch]
+            invocation = result.invocation.invocation_id
+            if not result.ok:
+                return [Adjudication(c, None, invocation, "failed") for c in batch]
+            by_slot = {}
+            for answer in result.parsed.answers:
+                by_slot.setdefault(answer.pair, answer)
+            out = []
+            for i, case in enumerate(batch):
+                answer = by_slot.get(f"P{i + 1}")
+                if answer is None:
+                    out.append(Adjudication(case, None, invocation, "missing"))
+                elif not set(answer.supporting + answer.contradicting) <= set(case.evidence_keys):
+                    out.append(Adjudication(case, None, invocation, "invalid_citation"))
+                elif answer.decision == "related" and answer.relation not in relations:
+                    out.append(Adjudication(case, None, invocation, "unknown_relation"))
+                else:
+                    out.append(Adjudication(case, answer, invocation, "ok"))
+            return out
+
+        workers = max(1, self.client.policy.concurrency)
+        with ThreadPoolExecutor(max_workers=workers) as pool:
+            results = [a for batch in pool.map(run, batches) for a in batch]
+        return results + skipped

thisness/assistant.py

@@ -0,0 +1,246 @@
+"""The review assistant (design 05 §5, PRD appendix A.15).
+
+A model answers an open review's own question from its case, and the answer is
+recorded as a ``ReviewRecommendation``: shown to the reviewer as a suggestion that
+can be applied to the board, never submitted, never a label. When the reviewer
+answers, their ``ReviewDecision`` records which recommendation they saw, so the
+model's agreement with people is measured on real decisions.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from itertools import combinations
+from typing import TYPE_CHECKING, Any, Literal
+
+from pydantic import BaseModel, Field
+
+from thisness.adjudicate import ReasonCode
+from thisness.core.components import ComponentRef
+from thisness.core.decisions import Actor, ReviewDecision, ReviewRecommendation
+from thisness.llm.client import BudgetExhausted, LLMClient
+from thisness.llm.privacy import filter_attributes
+from thisness.llm.prompts import Prompt
+from thisness.profiles.base import AttributeDefinition
+
+if TYPE_CHECKING:
+    from thisness.engine import Thisness
+
+MAX_COMPARISONS = 40
+
+
+class RecommendationAnswer(BaseModel):
+    resolution: Literal["same", "different", "groups", "related", "unsure"]
+    groups: list[list[str]] | None = None
+    relation: str | None = None
+    cited: list[str] = Field(default_factory=list)
+    reason_codes: list[ReasonCode] = Field(default_factory=list)
+    rationale: str | None = Field(default=None, max_length=800)
+
+
+def default_prompt() -> Prompt:
+    return Prompt.load("recommend_review", "2", RecommendationAnswer)
+
+
+@dataclass(frozen=True)
+class Recommended:
+    review_id: str
+    recommendation: ReviewRecommendation | None
+    invocation_id: str | None
+    status: str  # ok, invalid_groups, invalid_citation, unknown_relation, failed, skipped
+
+
+def review_labels(engine: Thisness, case: Any) -> tuple[dict[str, str], list[tuple]]:
+    """The labels a review's records and comparisons carry in the assistant's request:
+    records R1, R2, ... in the case's order; comparisons C1, C2, ... strongest first,
+    as ``(label, judgment, record label, record label, weight)``. The Workbench shows the
+    same labels, so a suggestion's rationale reads against the board."""
+    refs = {node.node_id: f"R{i + 1}" for i, node in enumerate(case.nodes)}
+    member_of = {member: node.node_id for node in case.nodes if node.kind == "entity"
+                 for member in engine.members(node.node_id)}  # fmt: skip
+
+    def ref_of(obs: str) -> str | None:
+        return refs.get(obs) or refs.get(member_of.get(obs, ""))
+
+    scored = []
+    for j in case.judgments:
+        a, b = ref_of(j.left_id), ref_of(j.right_id)
+        if a is None or b is None or a == b:
+            continue
+        weight = next((float(s.value) for s in j.scores
+                       if s.kind == "fellegi_sunter_weight"), None)  # fmt: skip
+        scored.append((abs(weight) if weight is not None else 0.0, j, a, b, weight))
+    ranked = sorted(scored, key=lambda x: (-x[0], x[1].decision_id))[:MAX_COMPARISONS]
+    return refs, [(f"C{i + 1}", j, a, b, w) for i, (_, j, a, b, w) in enumerate(ranked)]
+
+
+@dataclass(frozen=True)
+class _Request:
+    review_id: str
+    prompt: Prompt
+    payload: dict[str, Any]
+    refs: dict[str, str]
+    node_of_ref: dict[str, str]
+    current: dict[str, list[str]]
+    judgment_of: dict[str, str]
+    relations: list[str]
+
+
+@dataclass
+class ReviewAssistant:
+    client: LLMClient
+    model: str = "claude-sonnet-5"
+    prompt: Prompt = field(default_factory=default_prompt)
+
+    @property
+    def ref(self) -> ComponentRef:
+        return ComponentRef.of("resolver", "review_assistant", "1",
+                               {"model": self.model, "prompt": self.prompt.ref.ref})  # fmt: skip
+
+    def _prepare(self, engine: Thisness, review_id: str) -> _Request:
+        """Everything the request needs, read from the store."""
+        case = engine.review_case(review_id)
+        refs, labelled = review_labels(engine, case)
+        node_of_ref = {r: n for n, r in refs.items()}
+        entity_type = None
+        current: dict[str, list[str]] = {}
+        records = []
+        local = self.client.provider.local
+        for node in case.nodes:
+            current.setdefault(node.entity_id or node.node_id, []).append(refs[node.node_id])
+            profile = engine.profiles.get(engine.get_entity(node.entity_id)[0].entity_type) \
+                if node.entity_id else None  # fmt: skip
+            entity_type = entity_type or (profile.entity_type if profile else None)
+            definitions = dict(profile.attributes) if profile else {}
+            attributes = dict(node.attributes)
+            if node.kind == "entity":
+                attributes["observation_count"] = node.size
+                definitions["observation_count"] = AttributeDefinition(
+                    name="observation_count", data_type="integer")  # fmt: skip
+            fields, withheld = filter_attributes(attributes, definitions, local=local)
+            source = node.source.get("type") if node.source else None
+            records.append({"ref": refs[node.node_id], "record_id": node.node_id,
+                            "kind": node.kind, "source": source, "fields": fields,
+                            "withheld": withheld})  # fmt: skip
+
+        comparisons, judgment_of = [], {}
+        evidence = {e.evidence_id: e for e in engine.store.evidence(
+            sorted({e for _, j, *_ in labelled for e in j.evidence_ids}))}  # fmt: skip
+        for local_id, j, a, b, weight in labelled:
+            levels = {e.attribute: e.level for i in j.evidence_ids if (e := evidence.get(i))
+                      and e.attribute and e.level}  # fmt: skip
+            comparisons.append({"id": local_id, "a": a, "b": b, "by": j.actor.kind,
+                                "weight": None if weight is None else round(weight, 1),
+                                "verdict": str(j.verdict), "levels": levels})  # fmt: skip
+            judgment_of[local_id] = j.decision_id
+
+        profile = engine.profiles.get(entity_type) if entity_type else None
+        relations = list(profile.relations) if profile else ["related_to"]
+        payload: dict[str, Any] = {
+            "entity_type": entity_type, "question": case.question, "relations": relations,
+            "records": records, "current_groups": sorted(current.values()),
+            "comparisons": comparisons,
+        }  # fmt: skip
+        prompt = self.prompt.for_profile(engine.profiles.get(entity_type) if entity_type else None)
+        return _Request(review_id, prompt, payload, refs, node_of_ref, current, judgment_of,
+                        relations)  # fmt: skip
+
+    def _ask(self, request: _Request) -> Any:
+        """The model call: the only step that runs in parallel."""
+        try:
+            return self.client.call(request.prompt, model=self.model, payload=request.payload)
+        except BudgetExhausted:
+            return None
+
+    def _finish(self, engine: Thisness, request: _Request, answer: Any) -> Recommended:
+        """Check the answer and record it, one review at a time."""
+        review_id, prompt, refs = request.review_id, request.prompt, request.refs
+        node_of_ref, current = request.node_of_ref, request.current
+        judgment_of, relations = request.judgment_of, request.relations
+        if answer is None:
+            return Recommended(review_id, None, None, "skipped")
+        invocation = answer.invocation.invocation_id
+        if not answer.ok:
+            return Recommended(review_id, None, invocation, "failed")
+        parsed: RecommendationAnswer = answer.parsed
+        if not set(parsed.cited) <= set(judgment_of):
+            return Recommended(review_id, None, invocation, "invalid_citation")
+        groups = _partition(parsed, sorted(current.values()), sorted(refs.values()))
+        if parsed.resolution != "unsure" and groups is None:
+            return Recommended(review_id, None, invocation, "invalid_groups")
+        if parsed.resolution == "related" and parsed.relation not in relations:
+            return Recommended(review_id, None, invocation, "unknown_relation")
+        engine.store.register_component(self.ref, {"model": self.model})
+        recommendation = ReviewRecommendation(
+            decision_id=engine.ids.decision(), actor=Actor(kind="agent", id=self.model),
+            review_id=review_id, resolution=parsed.resolution,
+            groups=None if groups is None else tuple(
+                tuple(sorted(node_of_ref[r] for r in g)) for g in groups),
+            relation=parsed.relation if parsed.resolution == "related" else None,
+            reason_codes=tuple(parsed.reason_codes), rationale=parsed.rationale,
+            cited_judgments=tuple(judgment_of[c] for c in parsed.cited),
+            component_refs=(self.ref.ref, prompt.ref.ref),
+            invocation_id=invocation, created_at=engine.clock(),
+        )  # fmt: skip
+        engine.store.record_decisions([recommendation])
+        return Recommended(review_id, recommendation, invocation, "ok")
+
+    def recommend(self, engine: Thisness, review_id: str) -> Recommended:
+        request = self._prepare(engine, review_id)
+        return self._finish(engine, request, self._ask(request))
+
+    def recommend_many(self, engine: Thisness, review_ids: Sequence[str]) -> list[Recommended]:
+        """Recommendations for many reviews, the model asked ``policy.concurrency`` at a
+        time. Reading the store and recording answers stay sequential and in order."""
+        requests = [self._prepare(engine, r) for r in review_ids]
+        workers = max(1, min(self.client.policy.concurrency, len(requests)))
+        with ThreadPoolExecutor(max_workers=workers) as pool:
+            answers = list(pool.map(self._ask, requests))
+        return [self._finish(engine, r, a) for r, a in zip(requests, answers, strict=True)]
+
+
+def _partition(answer: RecommendationAnswer, current: list[list[str]],
+               refs: list[str]) -> list[list[str]] | None:  # fmt: skip
+    """The grouping an answer means, or None when it is not a valid one."""
+    if answer.resolution == "unsure":
+        return None
+    if answer.resolution == "same":
+        return [refs]
+    if answer.resolution == "different":
+        return current
+    if answer.resolution == "related":
+        return current if len(current) == 2 else None
+    groups = [list(g) for g in answer.groups or [] if g]
+    flat = [r for g in groups for r in g]
+    return groups if sorted(flat) == refs and len(flat) == len(set(flat)) else None
+
+
+def agreement(decisions: Sequence[ReviewDecision],
+              recommendations: dict[str, ReviewRecommendation]) -> dict[str, Any]:  # fmt: skip
+    """How often reviewers' answers matched the recommendation they were shown: the
+    whole grouping, and pair by pair (same group or not)."""
+    exact = pairs = agreed = n = 0
+    by_resolution: dict[str, list[int]] = {}
+    for decision in decisions:
+        rec = recommendations.get(decision.recommendation_id or "")
+        if rec is None or rec.groups is None or decision.groups is None:
+            continue
+        n += 1
+        mine = {node: i for i, g in enumerate(decision.groups) for node in g}
+        theirs = {node: i for i, g in enumerate(rec.groups) for node in g}
+        same_grouping = {frozenset(g) for g in decision.groups} == {frozenset(g)
+                                                                    for g in rec.groups}  # fmt: skip
+        exact += same_grouping
+        by_resolution.setdefault(rec.resolution, []).append(int(same_grouping))
+        for a, b in combinations(sorted(mine), 2):
+            if a in theirs and b in theirs:
+                pairs += 1
+                agreed += (mine[a] == mine[b]) == (theirs[a] == theirs[b])
+    return {
+        "reviews": n,
+        "exact": exact / n if n else None,
+        "pairwise": agreed / pairs if pairs else None,
+        "exact_by_recommendation": {k: sum(v) / len(v) for k, v in sorted(by_resolution.items())},
+    }

thisness/benchmark/__main__.py

@@ -0,0 +1,87 @@
+"""``python -m thisness.benchmark run``: resolve synthetic benchmarks and report.
+``python -m thisness.benchmark starter``: rebuild a shipped starter model."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from thisness.benchmark import organizations, people, taxa
+from thisness.benchmark.evaluate import PROFILES, run_benchmark
+from thisness.starter import write_starter
+
+GENERATORS = {"organization": organizations.generate, "person": people.generate,
+              "taxon": taxa.standard}  # fmt: skip
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="python -m thisness.benchmark")
+    sub = parser.add_subparsers(dest="command", required=True)
+    run = sub.add_parser("run", help="resolve benchmarks and print reports")
+    run.add_argument("--type", default="organization", choices=sorted(GENERATORS))
+    run.add_argument("--size", "--orgs", type=int, nargs="+", default=[805], dest="orgs",
+                     help="entities per benchmark")  # fmt: skip
+    run.add_argument("--seeds", type=int, nargs="+", default=[11])
+    run.add_argument("--json", action="store_true", help="print full reports as JSON")
+    run.add_argument("--reference", action="store_true",
+                     help="taxon only: WFO's own rows as observations too (design 06 §5)")  # fmt: skip
+    run.add_argument(
+        "--col",
+        action="store_true",
+        help="taxon only: the Catalogue of Life's rows too, a second authority",
+    )
+    run.add_argument(
+        "--authority",
+        default=None,
+        help="taxon only: the reference authority's source (default wfo)",
+    )
+    sub.add_parser("wfo-fixture", help="rebuild the shipped WFO fixture (fetches three families)")
+    sub.add_parser("uk-stage", help="fetch GLEIF and Companies House and stage them (design 07)")
+    sub.add_parser("uk-truth", help="count how good the GLEIF to Companies House join is")
+    uk_audit = sub.add_parser("uk-audit", help="read a sample of the join")
+    uk_audit.add_argument("--n", type=int, default=400)
+    sub.add_parser("uk-fixture", help="rebuild the shipped UK fixture from the staged data")
+    starter = sub.add_parser("starter", help="rebuild a starter model")
+    starter.add_argument("--type", default="organization", choices=sorted(GENERATORS))
+    starter.add_argument("--out", type=Path, default=None)
+    args = parser.parse_args()
+
+    if args.command == "run":
+        for n in args.orgs:
+            for seed in args.seeds:
+                options = {k: True for k in ("reference", "col") if getattr(args, k)}
+                profile = (PROFILES[args.type](authority=args.authority)
+                           if args.authority else None)  # fmt: skip
+                report, _, _ = run_benchmark(GENERATORS[args.type](n, seed=seed, **options),
+                                             profile=profile)  # fmt: skip
+                print(json.dumps(report.as_dict(), indent=1) if args.json else report.summary())
+    elif args.command.startswith("uk-"):
+        from thisness.benchmark import uk
+
+        if args.command == "uk-stage":
+            print(f"staged {uk.stage()}")
+        elif args.command == "uk-truth":
+            print(json.dumps(uk.truth_report(), indent=1))
+        elif args.command == "uk-audit":
+            report = uk.audit(n=args.n)
+            print(json.dumps({k: v for k, v in report.items() if k != "differing_names"}))
+            for d in report["differing_names"][:25]:
+                print(f"- {d['gleif']!r} | Companies House: {d['companies_house']!r}")
+        else:
+            print(f"wrote {uk.make_fixture()}")
+    elif args.command == "wfo-fixture":
+        target = Path(taxa.__file__).parent / "data" / "wfo_fixture.csv.gz"
+        taxa.write_rows(taxa.families(taxa.FIXTURE_FAMILIES), target)
+        print(f"wrote {target}")
+    else:
+        import thisness.profiles
+
+        profile = PROFILES[args.type]()
+        default = Path(thisness.profiles.__file__).parent / "data" / profile.starter_model
+        path = write_starter(profile, args.out or default)
+        print(f"wrote {path}")
+
+
+if __name__ == "__main__":
+    main()

thisness/benchmark/data/README.md

@@ -0,0 +1,13 @@
+# Benchmark data
+
+`wfo_fixture.csv.gz`: every species-level name (accepted, and synonyms with the accepted
+taxon each belongs to) in three plant families, Pinaceae, Betulaceae and Juglandaceae,
+from the **World Flora Online Plant List 2026-06**, as published on ChecklistBank
+(dataset 2004). The data is dedicated to the public domain under **CC0 1.0**; we credit
+it as a courtesy:
+
+> The World Flora Online Consortium et al. World Flora Online Plant List 2026-06.
+> https://www.worldfloraonline.org, via ChecklistBank (https://www.checklistbank.org/dataset/2004).
+
+Rebuild with `python -m thisness.benchmark wfo-fixture`. Other families are fetched on
+demand and cached under `~/.cache/thisness/wfo`.

thisness/benchmark/data/uk/README.md

@@ -0,0 +1,7 @@
+# UK organizations fixture
+
+A small slice of real data for tests (design 07): GLEIF Golden Copy Level 1 and 2 records registered with Companies House, and the Companies House records of those companies and their live near-namesakes.
+
+Contains GLEIF Golden Copy data (CC0 1.0) and Companies House data, public sector information licensed under the Open Government Licence v3.0.
+
+Built from: BasicCompanyDataAsOneFile-2026-10-01.zip (companies_house), 20261009-0800-gleif-goldencopy-lei2-golden-copy.csv.zip (lei2), 20261009-0800-gleif-goldencopy-rr-golden-copy.csv.zip (rr).