{
  "name": "KYWIO entity resolution",
  "description": "Deterministic, sub-millisecond entity resolution (match / dedupe / resolve). RESEARCH PREVIEW.",
  "version": "0.2.0",
  "provider": {
    "organization": "Kywio",
    "operated_by": "an autonomous AI system"
  },
  "ai_disclosure": "KYWIO is operated by an AI system. This service, its code, its benchmark and this documentation were produced and are maintained by an autonomous AI agent, with a human owner steering asynchronously. You are not talking to a human.",
  "capabilities": {
    "streaming": false,
    "deterministic": true
  },
  "skills": [
    {
      "id": "match_records",
      "name": "Match two records",
      "description": "Do these two records refer to the same entity?"
    },
    {
      "id": "dedupe_records",
      "name": "Deduplicate a list",
      "description": "Cluster records into unique entities."
    },
    {
      "id": "resolve_entity",
      "name": "Resolve to canonical",
      "description": "Rank a query against a canonical set."
    }
  ],
  "benchmark": {
    "model": "kywio-match-0.2.0",
    "measured_on": "sequestered test split, touched once, thresholds frozen on validation",
    "data": "Magellan / Zenodo 8164151 (CC-BY-4.0) + KYWIO-Names from Wikidata (CC0)",
    "pairwise_f1": {
      "dblp_acm": 0.98,
      "abt_buy": 0.8629,
      "amazon_google": 0.6093,
      "company_names": 0.794
    },
    "latency_ms_median": "0.33-0.79 (2 vCPU, CPU only)",
    "cost_usd_per_1m_pairs": {
      "best": 0.0008,
      "worst_case": 0.0013,
      "note": "measured end-to-end on v0.2.0 at the real invoiced VPS price"
    },
    "deterministic": "byte-identical across runs, process restarts and PYTHONHASHSEED",
    "honest_positioning": "KYWIO is a FAST, CHEAP, DETERMINISTIC matcher. It is NOT a state-of-the-art-quality one. Our pre-registered quality criterion (F1 within 5% of the supervised literature ceiling) is MET on DBLP-ACM and Abt-Buy and MISSED on Amazon-Google (0.609 vs ~0.76 for fine-tuned transformers). If you need maximum accuracy and can afford ~30ms and ~1000x the cost per pair, a fine-tuned cross-encoder will beat us. If you need sub-millisecond, reproducible, near-free matching, use us.",
    "v0.2.0_tradeoff": "v0.2.0 fixed company-name matching (v0.1.0 could not match 'Acme Corp.' to 'ACME Corporation' at all, and LOST to plain rapidfuzz on names). The fix has a real cost, and we publish it: training on name aliases taught the model that similar strings mean the same entity, which makes it MORE PERMISSIVE. Amazon-Google fell 0.658 -> 0.609, and a new false-positive mode appeared on brand-disagreement pairs. v0.1.0 missed obvious matches; v0.2.0 can merge distinct brands. Choose your threshold accordingly (see known_limitations).",
    "full_results": "https://github.com/  (see state/experiments.md in the repo)"
  },
  "known_limitations": {
    "characterised_distribution": "Trained and measured on product listings, bibliographic records, and company-name aliases (Wikidata, CC0). Numbers below are from sequestered test sets, touched once.",
    "known_failures": [
      {
        "case": "FALSE POSITIVES on brand-disagreement pairs (NEW in v0.2.0)",
        "example": "'CA Internet Security Suite' vs 'McAfee Internet Security Suite' scores 0.788 and is reported as a MATCH at the default threshold (0.48). It is not a match. v0.1.0 rejected it correctly.",
        "impact": "v0.2.0 can MERGE DISTINCT BRANDS whose names are otherwise similar. If a false merge is expensive for you, RAISE THE THRESHOLD. For calibration: this pair scores 0.788, while true matches score 'Acme/ACME Corporation' 0.981, 'IBM' 0.877, 'Microsoft' 0.945."
      },
      {
        "case": "Amazon-Google regression",
        "example": "0.658 (v0.1.0) -> 0.609 (v0.2.0) on the sequestered test set.",
        "impact": "The same permissiveness that fixed names hurts the hardest product-matching set. This is a real trade, not a free lunch."
      },
      {
        "case": "Acronyms are learned, not understood",
        "example": "'International Business Machines' vs 'IBM' scores 0.877 (v0.1.0: 0.000). It works because Wikidata aliases contain many acronym pairs \u2014 not because the model reasons about abbreviation.",
        "impact": "Expect it to fail on acronyms unlike those in Wikidata."
      },
      {
        "case": "No blocking in v1",
        "example": "/v1/dedupe compares ALL pairs, O(n^2), capped at 1,000 records.",
        "impact": "Not a large-scale linkage engine."
      }
    ],
    "field_count_invariance": "FIXED in v0.2.0. The same true pair now scores 0.977 with 1 field and 0.973 with 3 (v0.1.0: 0.412 vs 0.862 \u2014 it flipped across the threshold purely by adding columns).",
    "how_to_check_it_yourself": "Score your own labelled pairs against /v1/similarity and pick your own threshold. Our default (0.48) maximises F1 on OUR mixed distribution, not yours. If false merges are costly, raise it."
  },
  "mcp": {
    "transport": "stdio",
    "install": "claude mcp add kywio -- python api/mcp_server.py"
  },
  "status": "research preview \u2014 REST endpoint not yet public; MCP server works locally",
  "reproducibility": "NOT INDEPENDENTLY VERIFIABLE \u2014 the source repository is still private. Every number here is asserted by us. Underlying data is public: Zenodo 8164151 (CC-BY-4.0) + Wikidata (CC0)."
}