DEV Community: Tae Kim

The decisions in my entity resolution pipeline that I still make myself

Tae Kim — Thu, 01 Oct 2026 02:49:03 +0000

A few months ago I spent a couple of days debugging blocking mismatches that I couldn't explain. I'd added a Japanese securities data source and a bunch of subsidiary nodes weren't matching their Korean counterparts. Asked for help checking the blocking key function. Got back a version that looked right. Ran it. Still had mismatches. Tried again.

Eventually I just pulled up the raw input data and looked at it. The source had a lot of entries formatted as 合同会社 XYZ. That's a godo kaisha — basically a Japanese LLC. My blocking key function stripped 株式会社 and a few other common forms, but I'd never added 合同会社. So those records were producing blocking keys that didn't match their Korean counterparts, and those pairs never entered the candidate pool.

The fix was one regex line. I'd lost two days on it.

What I kept thinking about after was: the AI couldn't have caught this. It was generating correct general blocking functions. But whether 合同会社 needed to be in the strip list depended entirely on what was in my specific dataset. You can't answer that from the code. You have to look at the data.

Since then I've started paying attention to when a question I'm asking is really a "what's in my data" question in disguise. Confidence threshold questions often are. I'll ask what threshold I should use and get an answer that's been reasoned out from general principles. It'll sound right. But the right threshold for me depends on what the Korean-English pairs in my training set actually look like, and what it costs me when the resolver merges two nodes that shouldn't be merged versus when it misses a merge it should have made. That's not in any prompt I can write.

I haven't fully figured out how to screen for these. Sometimes I catch it before I go down a path, sometimes I don't until I've already spent time on the wrong thing. The 合同会社 case was the one where I lost the most time to it.

I build er-api, a multilingual entity resolution service for Korean, Japanese, Chinese, and English corporate data. More at hannune.ai.

Graph RAG: where it actually breaks

Tae Kim — Wed, 30 Sep 2026 02:37:58 +0000

Neo4j with a working schema: two days. Cypher traversal for the relationships I needed: another day or two, once I knew what I was querying. The graph structure, once committed, stayed mostly stable.

That's not where things kept breaking.

The routing problem

When someone asks "what companies are exposed to semiconductor export restrictions?" the system needs to figure out whether to do graph traversal, vector search, or some combination. Getting this wrong doesn't produce an obvious error. It returns something that cites real sources and sounds confident. It just misses context that was sitting in the graph the whole time.

I had one case that stayed with me. A query about a Korean chipmaker's supplier network kept returning news results. The answer was plausible — recent articles about the company, relevant details. It took longer than I'd like to admit to notice that the supplier relationships were already in the graph. The system just wasn't routing that query there. Once I found the gap, the fix was two lines of code. Finding it was the work.

The routing logic I ended up with uses the query's dependency structure as a signal:

def route_query(query: str, graph_searcher, vector_searcher) -> list:
    relational_signals = ["supplier", "subsidiary", "controlled by", 
                          "exposed to", "connected to", "supply chain"]

    needs_graph = any(s in query.lower() for s in relational_signals)

    if needs_graph:
        entity_ids = graph_searcher.find_related(query)
        return vector_searcher.search_scoped(query, entity_ids)
    else:
        return vector_searcher.search(query)

The signal list is hand-tuned and the scoping logic has edge cases. But it reduced the miss rate more than anything else I tried.

Entity quality doesn't stay clean

The second place things break is entity quality, and this one is more insidious because it's gradual.

The initial entity resolution pass establishes a set of merged entities. After that, the source data keeps changing. A company I had cleanly resolved was acquired six months into the project. Post-acquisition news started using a new parent company name alongside the old subsidiary name. The graph started accumulating both as separate nodes for the same underlying entity.

Graph traversal from the old node gave one picture; traversal from the new node gave a different one. Neither looked wrong in isolation.

MATCH (e:Entity {name: "Old Name"})-[:SUPPLIES]->(s:Entity)
RETURN s.name, s.country

-- If the same entity now also exists as "New Name" post-acquisition,
-- those relationships are on a different node entirely

I treat entity quality as something that degrades continuously now, not a state you establish once. Running a periodic audit of merged pairs helps — checking whether the alias-to-entity mapping still makes sense for recently active entities.

from datetime import date, timedelta

def stale_merges(registry: dict, days_threshold: int = 90) -> list:
    cutoff = date.today() - timedelta(days=days_threshold)
    stale = []
    for entity_id, meta in registry["entities"].items():
        last_verified = meta.get("last_verified")
        if last_verified:
            verified_date = date.fromisoformat(last_verified)
            if verified_date < cutoff and meta.get("alias_count", 0) > 3:
                stale.append(entity_id)
    return stale

The honest version: figuring out which merged pairs have actually gone stale is still mostly manual review. The detection is automatable. What to do with a flagged pair isn't something the code decides.

I build er-api, a multilingual entity resolution service for Korean, Japanese, Chinese, and English corporate data. More at hannune.ai.

Why I can't run Splink in an API call

Tae Kim — Mon, 28 Sep 2026 03:15:15 +0000

I got confused about this for longer than I expected.

The 2asy.ai news pipeline uses Splink. Company mentions come in with each article batch, Splink runs pairwise comparison against everything already in the registry, clusters form, the registry updates. Usually takes about 90 seconds. Sometimes longer. Nobody is waiting for it.

When I started building the ER API, I thought the API would just be a lighter version of that. Call Splink, get a match, return it. The response latency problem hit me within the first day of prototyping. Splink's actual comparison work involves blocking across the full corpus, scoring candidate pairs, then an EM step to calibrate probabilities. On a corpus with a few hundred thousand records, you're looking at seconds of compute, not milliseconds. You can't put that in the path of an HTTP request that someone's polling from their application.

So the API compares an incoming name against a pre-computed candidate index and returns the top result above a threshold. That's fast enough. What I didn't think through carefully at the start was what you lose by doing it that way. Splink's EM step sees the full distribution of records together. Some pairs that look ambiguous in isolation are only resolvable in context because the EM algorithm essentially gets to vote across the whole population. The API doesn't have that. Each query is independent.

I worked around the latency problem reasonably well. The threshold question has been messier. When a match comes back at 0.71, what should the caller do with that? In the news pipeline I can defer uncertain pairs to a review queue and come back to them. In the API you have to give the caller something. My first attempt was to just return the score and let callers use their own threshold. What I didn't anticipate was that most callers treat any result above their threshold as a hard match, regardless of how close to the threshold it is. The docs now include threshold guidance for different use cases, but I'm still getting questions about this, so I probably haven't described it clearly enough yet.

Model retraining is the one I thought about least and arguably got most wrong. I collect labeled pairs continuously and retrain the Splink model for the pipeline every few weeks. Doing the same for the API turned out to be a problem. Even a small retrain shifts match probabilities slightly. If the API returns 0.84 for a query this week and 0.79 for the same query after a retrain, anyone who built automation against the API and didn't read the changelog will notice. I now pin the API to a specific model version and do explicit releases instead. This is more conservative than I'd like, but I don't have a cleaner answer.

The 2asy.ai pipeline still uses full Splink batch resolution. The API handles point queries where a caller needs an answer immediately and doesn't have the corpus context to run it themselves. I knew from the start that these were different use cases. What I underestimated was how different the constraints would be.

I build er-api, a multilingual entity resolution service for Korean, Japanese, Chinese, and English corporate data. More at hannune.ai.

The normalization step that breaks before your ER model does

Tae Kim — Fri, 25 Sep 2026 03:10:47 +0000

I spent three weeks tuning near-threshold match scores before realizing the pairs I was most worried about weren't getting bad scores. They weren't generating candidate pairs at all.

The thing I thought would fix it didn't. My first guess was blocking key design. I'd read enough about the invisibility of blocking errors that I figured the issue had to be there. I checked the blocking key function, checked the bucket sizes, didn't see anything obviously wrong. The pairs I was looking for were just absent.

Then I added a simple audit: take 30 pairs that should match, print the blocking keys side by side. First run was Japanese companies from a securities exchange I'd added a few weeks before. Out of 30 pairs, 11 weren't generating matching keys.

The exchange uses full-width ASCII characters in company names. ＡＢＣ株式会社 uses full-width Latin letters (U+FF21 and so on), not regular ASCII. I hadn't known this was a thing. Ａ and A are different code points, so the normalized name hashes to a different key.

import unicodedata
name = unicodedata.normalize("NFKC", name)

NFKC handles this. I ran the audit again, got 30 of 30. Then I ran the same audit on Korean data from a corporate registry and found a different problem.

Korean company names have the entity type in multiple forms: 주식회사 ABC, ABC(주), sometimes just ABC㈜ where ㈜ is a single precomposed Unicode character at U+3378 in the CJK Compatibility block. My stripping code handled 주식회사 and (주). It didn't handle ㈜ because that's not a sequence of three characters; it's one codepoint that looks like a parenthetical when rendered.

KOREAN_LEGAL_FORMS = [
    r"주식회사",
    r"유한회사",
    r"\(주\)",
    r"㈜",   # U+3378, precomposed, won't match the spelled-out pattern
    r"\(유\)",
    r"㈔",   # U+3354
]

Japanese has ㈱ (U+3231) and ㈲ (U+3232) the same way. I found those in the same audit session.

The ordering thing tripped me up a bit. My thought was to run NFKC first and that would expand the precomposed symbols so the stripping patterns would match them. It doesn't work that way. NFKC doesn't decompose those particular codepoints; they pass through intact. So the precomposed forms have to be in the stripping list explicitly. Running NFKC before stripping is still right because it handles the full-width ASCII, but it doesn't help with the precomposed legal symbols.

There's still a category I don't have a clean answer for. Some Japanese company names use older traditional character forms that predate postwar simplification. 國 and 国 refer to the same character. NFKC handles some variant pairs but not all. I've been adding them manually to a lookup table when they turn up in audits. That's obviously not comprehensive. At some point I should probably run a dedicated audit against a list of the known variant pairs, but I haven't done it, partly because I'm not sure how to get that list and partly because the other normalization issues got fixed first and this one fell off the queue.

The reason these are hard to catch is that they don't show up in any metric unless you build the blocking recall audit yourself.

I build er-api, a multilingual entity resolution service for Korean, Japanese, Chinese, and English corporate data. More at hannune.ai.

Where I got labeled training data for Korean-Japanese-Chinese entity resolution

Tae Kim — Wed, 23 Sep 2026 03:11:35 +0000

Around pair 400 of the manual annotation batch, I got to a Korean holding company and its Japanese parent. The Japanese database had the company listed as a joint venture, the Korean filing described it as a wholly-owned subsidiary. Same entity, but the ownership description was genuinely different between sources. I marked it as a match since the names clearly referred to the same company, but I wrote a note that I still don't know what to do with.

That was about a month in. I ended up reviewing around 2,000 pairs by hand before I had enough coverage to feel reasonably confident in the KR-JP and KR-ZH models.

The reason it got to manual annotation: I couldn't find a public labeled dataset for Korean-Japanese-Chinese cross-lingual corporate name matching. For English-only ER, there are open sources. For this specific domain, I didn't find anything usable.

The Korean-English piece came together faster than I expected. Korean financial disclosure filings (DART) require companies to report both the Korean legal name and the English name. That turned out to be a clean source of verified KR-EN pairs. The company certified both names in a regulatory document, so I didn't have to guess whether they referred to the same entity.

def fetch_dart_name_pairs(company_code: str) -> dict:
    url = "https://opendart.fss.or.kr/api/company.json"
    params = {"crtfc_key": DART_API_KEY, "corp_code": company_code}
    resp = requests.get(url, params=params)
    data = resp.json()
    return {
        "ko": data.get("corp_name"),
        "en": data.get("corp_name_eng"),
    }

Scraping recent DART filings got me a few thousand KR-EN positive pairs. Combined with negatives generated by sampling companies from different industry sectors, the KR-EN Splink model got decent coverage early.

The KR-JP and KR-ZH pairs didn't have an equivalent source. I went looking for companies with cross-listed securities that would appear in databases across multiple languages. Found maybe 800-900 verified triplets that way. Not many, but enough to get an initial model to a usable state for the core coverage.

The 2,000 manual annotations were the gap-filler. Mostly companies in the near-threshold band of early model runs, which sounds principled but in practice meant sitting with a lot of cases where I wasn't sure. Japanese holding company naming conventions have edge cases I'd never thought about before. A company could be listed under a regional holding name in Japanese filings but appear under the global brand in Korean corporate registries. Not wrong, just a different layer of the corporate structure.

The KR-EN model is the one I trust most. The KR-JP and KR-ZH models have held up for the core coverage but I've seen them struggle on cases that weren't well represented in the training set. I add pairs when I find errors in production, but it's slow.

I build er-api, a multilingual entity resolution service for Korean, Japanese, Chinese, and English corporate data. More at hannune.ai.

What Splink actually runs on DuckDB when it scores entity pairs

Tae Kim — Tue, 22 Sep 2026 02:36:36 +0000

When I added Splink to the ER API, the registry was at 44,798 entities. Before touching any configuration knobs, I looked at the SQL it was generating. I expected opaque query strings. What came out was readable enough that I could follow the logic directly.

The blocking step generates something like this:

SELECT
    l.entity_id AS entity_id_l,
    r.entity_id AS entity_id_r,
    l.name_normalized AS name_l,
    r.name_normalized AS name_r
FROM entities AS l
INNER JOIN entities AS r
    ON LEFT(l.name_normalized, 4) = LEFT(r.name_normalized, 4)
WHERE l.entity_id < r.entity_id

LEFT(name_normalized, 4) is the blocking key. Entities that don't share those first four characters don't get compared at all. At 44,798 entities this brought candidate pairs from roughly 2 billion down to about 400,000.

The cross-join on the full entity table was what was slow. I caught this by looking at the DuckDB query plan while the blocking step ran — it was sitting there doing a lot more work than I wanted. Adding an index on the blocking key column fixed it immediately. Not complicated once I knew where to look, but I wouldn't have looked there without reading what was actually running.

What the EM pass is doing

For each candidate pair, Splink builds comparison features before the EM loop:

SELECT
    entity_id_l, entity_id_r,
    CASE WHEN name_l = name_r THEN 1 ELSE 0 END AS exact_match,
    jaro_winkler_similarity(name_l, name_r) AS jaro_winkler_sim,
    CASE WHEN country_l = country_r THEN 1 ELSE 0 END AS same_country
FROM candidate_pairs

The EM loop ran fast once I had the candidate table. DuckDB handles this in-process, so there's no serialization overhead between iterations. On my machine, 400,000 pairs, the whole convergence took a few seconds. That part of the pipeline wasn't a problem.

What I spent a disproportionate amount of time on was preprocessing. Name normalization for Korean, Japanese, and Chinese inputs has a lot of edge cases, and the blocking key construction amplifies whatever noise gets through. Japanese company name suffixes alone took an afternoon to handle consistently — 株式会社 shows up at the front in some sources and the back in others, abbreviated in a few more. Once I had a normalization that wasn't silently introducing variance into the blocking key, I'd spent more hours there than on everything inside Splink's own configuration combined.

None of that is a Splink problem. The library doesn't know what language your inputs are in. But if you're running entity resolution over multilingual corporate names, the normalization you build before Splink touches the data will probably be where you spend most of your time. The EM loop will be fine.

I build er-api, a multilingual entity resolution service for Korean, Japanese, Chinese, and English corporate data. More at hannune.ai.

Your entity resolution pipeline works on database records. Then you point it at news text.

Tae Kim — Thu, 17 Sep 2026 03:06:13 +0000

I built the entity resolution pipeline at 2asy.ai against structured registry data. I benchmarked it against structured registry data. The match scores looked good. I moved on.

About a month later I started ingesting news articles. The first batch turned into two weeks of cleanup.

What I hadn't tested was what happens when the source text doesn't use formal company names. News doesn't. A Korean financial article calls "삼성전자 주식회사" just "삼성." A piece in English calls it "Samsung" without specifying which Samsung entity, because to a human reading with context, it's obvious which one. The pipeline had no reading context. It had a blocking key built on the first four characters of a normalized name.

"삼성" hits the same blocking bucket as Samsung Electronics, Samsung SDI, Samsung C&T, and a dozen other entities under the group umbrella. The EM scoring then gets candidate pairs with name similarity 1.0 across all of them and nothing else to work with.

ON LEFT(l.name_normalized, 4) = LEFT(r.name_normalized, 4)

This was the blocking rule. It was designed for formal names where "Samsung Electronics" and "삼성전자" both normalize to something starting with "sams." It's also what causes a short news mention to block with every Samsung subsidiary in the registry.

What I added was a post-scoring filter using signals from the article itself. The article a mention comes from has context: what other entities appear nearby, what sector terms show up in the paragraph. When the top match by name similarity has no overlap with those signals, I look at the second-best match.

def extract_context_signals(article: dict, mention_span: tuple) -> dict:
    window = article["text"][max(0, mention_span[0]-200):mention_span[1]+200]
    return {
        "mentioned_with": extract_entity_mentions(window),
        "sector_keywords": extract_sector_terms(window),
        "article_category": article.get("category", "unknown"),
    }

This helped with the Samsung group disambiguation specifically. It doesn't do much for companies that don't have siblings with similar names. And when the article context is thin — short breaking news items especially — the signals aren't reliable enough to use.

I also raised the confidence floor for what I'm calling informal mentions: short Korean-character forms, English names that don't include the entity's legal suffix. The threshold for a two-character Korean name merging to a registry entry is higher than for a full formal name match.

if mention_is_short_informal(mention_text, source_language):
    threshold = max(threshold, 0.90)

The 0.90 came from watching the false-merge rate and adjusting until it dropped to something workable. It's not principled.

The benchmark I ran when building this is still the benchmark I'm running. It's all registry-vs-registry pairs. I don't have a labeled test set for news mentions, so I don't actually know what the precision-recall curve looks like for the domain I'm now running against daily. That's the part I'm not comfortable with.

I build er-api, a multilingual entity resolution service for Korean, Japanese, Chinese, and English corporate data, used in 2asy.ai for news-to-knowledge-graph ingestion. More at hannune.ai.

When I killed the Korean version: what channel mismatch actually looks like

Tae Kim — Tue, 15 Sep 2026 03:44:39 +0000

About three months into building the Korean version, I showed the product to a financial analyst at a Korean institutional investor. He scrolled through the interface for maybe thirty seconds, then said something like: "we already have Bloomberg for data, what I need is something I can hand off."

The "hand off" part is what stuck. He needed a PDF or an Excel file, something he could email to a manager. The graph query interface I was showing him was not the answer.

I kept working on the project for a few more weeks anyway. The pipeline was running. I told myself I was still gathering information.

Some background: 2asy.ai tracks tariff policy changes and how they propagate to specific companies. The basic idea is that you can crawl policy and trade news, figure out which companies sit in the affected supply chains, and make that queryable. The entity resolution work is the hard part of it, which is mostly what the ER API does. When I decided to do a Korean-language version, it looked tractable because I'd done most of that infrastructure already. Mainly crawl pipeline work and some frontend localization to do on top.

By the time I showed the analyst that demo, I'd had a few other conversations in the same vein. Different people, similar answer. Korean institutional finance and compliance people I was talking to wanted a deliverable they could hand to someone else, not a tool they'd query themselves. The B2B buyers I'd built the international version for had already decided to integrate vendor risk data programmatically. Most of the Korean buyers I was reaching hadn't made that decision, or weren't the decision-makers who would.

I paused it. I kept the crawl pipeline and the entity resolution work because those are directly reusable if a reporting-oriented distribution path shows up. But I stopped maintaining it as an active product and turned off the scheduled jobs.

Looking back, I'm still not entirely sure when I made the decision versus when I just stopped maintaining it. Somewhere around week twelve those converged.

I build er-api, a multilingual entity resolution service, and 2asy.ai, a trade intelligence graph. More at hannune.ai.

What the retrieval layer of a Graph RAG system actually looks like

Tae Kim — Fri, 11 Sep 2026 03:25:08 +0000

The first version retrieved everything. Every node reachable from the seed entity, up to four hops. The context window hit 8,000 tokens on a basic query about a mid-size Korean manufacturer. The model started confusing entities.

I pulled it back to 50 nodes, which is where it still is. I don't love that number. It's a hard cutoff that causes real problems for large corporate groups — Samsung Electronics has hundreds of subsidiaries and a query about their supply chain exposure hits the limit before returning a complete picture. But 50 is where the model stops confusing things and starts giving useful answers, and I haven't found a smarter expansion strategy that changes that tradeoff.

The system is a Graph RAG layer over a 50 million-row supply chain knowledge graph. The entity resolution took about two weeks to get right. The retrieval layer itself took three days. Here's what the retrieval actually does.

Every retrieval starts from seed entities. For a query like "what is Samsung SDI's exposure to US tariffs on Korean steel," the first step is which nodes in the graph correspond to "Samsung SDI" and "US tariffs." I run this through an entity lookup that checks normalized names and aliases:

def identify_seed_entities(query_text: str, session) -> list[str]:
    entities = extract_entities(query_text)
    results = []
    for entity_mention in entities:
        candidates = session.run("""
            MATCH (e:Entity)
            WHERE e.name_normalized CONTAINS $mention_normalized
               OR any(alias IN e.aliases WHERE alias CONTAINS $mention_normalized)
            RETURN e.id, e.name, e.canonical_type
            ORDER BY e.mention_count DESC
            LIMIT 3
        """, mention_normalized=normalize(entity_mention)).data()
        if candidates:
            results.append(candidates[0]["e.id"])
    return results

mention_count ranks entities by how many source documents they appear in. This is a rough importance proxy. For "Samsung SDI" it works fine. For more ambiguous mentions it sometimes picks the wrong candidate, especially for smaller companies that share name fragments. I haven't fixed that properly.

From the seed nodes, the subgraph expansion follows supply chain relationship types and cuts off at three hops. Four hops started returning nodes that were technically connected but not relevant to any reasonable interpretation of the query. A steel tariff affecting a Korean parts supplier affecting a construction equipment company is three hops and stays useful. The fourth hop typically reached conglomerates that own everything and added noise.

result = session.run("""
    MATCH path = (seed:Entity {id: $seed_id})-[r:SUPPLIES_TO|SOURCES_FROM|OWNS|CONTROLS*1..3]-(connected)
    WITH connected, length(path) AS hops
    WHERE hops <= 3
    RETURN connected.id AS entity_id, connected.name AS entity_name, hops
    ORDER BY hops ASC, connected.document_count DESC
    LIMIT 50
""", seed_id=seed_id)

After getting the subgraph, I fetch the source document excerpts that were asserted through those entities. These are the actual facts — the sentences from filings, news articles, procurement documents that describe the relationships:

result = session.run("""
    MATCH (e:Entity)-[r:ASSERTED_IN]->(d:Document)
    WHERE e.id IN $entity_ids
    RETURN e.name AS entity_name,
           d.excerpt AS fact_text,
           d.source AS source,
           d.published_at AS published_at,
           r.assertion_confidence AS confidence
    ORDER BY r.assertion_confidence DESC, d.published_at DESC
    LIMIT 100
""", entity_ids=entity_ids)

The hundred-fact fetch gets trimmed to forty before going to the model. The trim is TF-IDF ranking against the query terms, which is coarse but seems to work. The bigger problem is that facts from entities reached through low-confidence ER merges get the same treatment as facts from directly verified sources. I flag anything below 0.80 confidence with [uncertain] in the context, but that's a manual addition after discovering the model was treating all facts equally regardless of how confident the underlying merge was.

Packaging the final context is straightforward: facts sorted by confidence, each labeled with source and date. Uncertain ones get the flag. The model prompt says to treat flagged facts as preliminary.

What takes the most time isn't any of this. It's the cases where the query involves an entity the graph doesn't have at resolution quality. The graph might have "Samsung SDI" resolved, but a smaller battery cell supplier mentioned in a procurement document might exist as a raw string node that never got merged with anything. The retrieval finds it, returns facts, and the model reasons off it as if it were a resolved entity. I currently have no way to flag "this entity wasn't fully resolved" at retrieval time. That's the next thing I need to add.

I build er-api, a multilingual entity resolution service for Korean, Japanese, Chinese, and English corporate data. More at hannune.ai.

Building an investing knowledge graph, part 6: if you're merging data from more than one source, you'll hit this

Tae Kim — Thu, 10 Sep 2026 02:55:22 +0000

Building an investing knowledge graph, part 6: if you're merging data from more than one source, you'll hit this

Since part 5 went up, I've had two conversations worth writing about. One was with someone building a financial news aggregation system who wanted to know if the ER setup here would work for their case. The other was with someone doing KYC screening who asked roughly the same question. Those conversations are what prompted this final part.

The financial news question had an obvious answer: yes, with some caveats about cross-language blocking. The KYC question took me longer, because the error tolerance is so different that I wasn't sure how much of what I built would actually transfer.

The KYC conversation

The person I talked to was working on sanctions screening. Their problem was name matching: entity strings from incoming documents against a registry of flagged persons and organizations. The description of the ER problem was familiar enough that I recognized it immediately.

What I had to think through more carefully was what the differences meant in practice. In the investing graph, a false negative means a traversal stops short. Two nodes that should be the same entity exist as separate nodes, and a path that should go through them stops at the first one. The graph is less useful, and you can often tell something is wrong because you're getting empty results where you expect some.

In sanctions screening, a false negative is an entity that should have been flagged clearing a check it shouldn't have. The downstream consequences are not "the graph is less useful." This changes how you'd set the threshold, and it probably changes how you'd approach training data. The model I've been running was tuned for a corpus where some missed merges are acceptable in exchange for keeping false positives low. For compliance tooling, that tradeoff goes the other way. I couldn't tell the KYC person "use the same model and threshold" and be confident they'd get results they could actually rely on.

So: the core architecture is the same. The pairwise scoring, the registry with a stable and pending boundary, the review layer for uncertain pairs. But the model would need to be retrained on labeled pairs from their actual domain, and the threshold would need to be set differently. These aren't small caveats. Blocking strategy would probably change too, because person name matching across languages is harder than company name matching in English.

The financial news question

This one was more tractable. They were ingesting from Bloomberg, a Chinese-language wire service, and some regional outlets. "Tesla, Inc." and "特斯拉" and "the EV maker" arriving in the same week.

The architecture question I could answer directly: yes, the same setup applies. The harder question was about cross-language blocking. For English company names, string normalization gets you a long way. Strip legal suffixes, lowercase, collapse whitespace, and most aliases cluster cleanly enough that phonetic blocking on the normalized form works. For Chinese-English matching, you need something else.

I spent some time thinking through what I'd actually try. One approach is alias generation during ingestion: before a string hits the resolver, you run it through a step that produces language variants and stores them as additional candidates. Then blocking happens on normalized alias strings rather than on raw input. The problem with this is that you're trusting the alias generation step, which introduces a new source of noise. I've thought about this but haven't implemented it, and I was honest with the person asking that this was speculation rather than something I'd tested.

The main takeaway from both conversations is that the registry architecture is more transferable than the model itself. The idea of maintaining a stable set of committed decisions versus a pending set of uncertain pairs under review, and serving only the stable set to external callers, holds regardless of what domain you're matching in. The specific model weights and threshold values don't hold.

What I would tell someone starting from scratch

This is the part I'm most uncertain about writing, because there's a gap between "what I learned from this specific project" and "what would generalize to your project."

The concrete thing I'd say: budget for registry maintenance in a way you probably won't. The ongoing cost of running this system is managing accumulated state, not running inference. Close to 48,000 entities and aliases have accumulated over months of ingestion. Some of those decisions were made when the threshold was still being calibrated. I know this in aggregate because I watched the model improve; I don't know which specific entries are wrong without re-running the full corpus. That re-run is still on the list.

I'd also say: the blocking step is where I lost the most time to underestimation. It's easy to focus on the model and assume that if you have good coverage you'll catch most matches. The model doesn't see pairs that didn't make it through blocking. If your blocking strategy misses a class of matches systematically, you won't know from looking at the model's output alone.

The third thing, and I've mentioned this before but it bears repeating at the end of a series: Splink is doing the real probabilistic lifting here. It's a well-maintained open-source library, and I'd recommend starting there before building anything custom.

ER API and what comes next

The investing knowledge graph is still running. The entity resolver is live on Railway as ER API, and I'm expanding access based on how early users are actually using it.

The endpoints are /v1/resolve for single string resolution and /v1/splink-pairs for batch candidate scoring. If you're running into the entity resolution problem in your own pipeline and want to try the service, there's a form at hannune.ai.

All six parts

Part 1: From "does this news matter" to a graph I can query
Part 2: The query SQL can't answer
Part 3: Same company, seven names
Part 4: Building the resolver
Part 5: What LIVE actually means

Built on Splink for probabilistic record linkage.

Building an investing knowledge graph, part 5: what LIVE actually means

Tae Kim — Wed, 02 Sep 2026 02:37:13 +0000

Building an investing knowledge graph, part 5: what LIVE actually means

Part 4 ended with the resolver working locally and me calling it live on Railway. That framing glossed over a gap. Something running locally and something running in production are different in ways that are obvious in retrospect and invisible until they bite you.

Here's what changed once I had a caller that wasn't me.

The first thing that breaks when someone else calls your API

The investing knowledge graph pipeline was the only caller for a long time. I knew its call patterns. I'd written both sides. The error budget was implicit — if something failed, I fixed it and kept going.

The first external caller changed that. When the API started returning errors for them, there was no "I'll fix it and retry." There was a broken integration on their end, and they had no context for diagnosing it.

The specific failure was unhelpful: a 500 with a generic error message on a request that had worked in my own testing. It took debugging from both ends to isolate the cause. The request was valid. The issue was that it hit the API during a window when the registry backend was mid-write, and the response came back internally inconsistent — some aliases resolved correctly, others returned stale data.

This wasn't a bug in the resolver logic. It was a backend durability problem I hadn't needed to care about when I was the only caller.

What the backend switch actually fixed

Locally, I used a file-based registry backend. The registry serializes to a JSON file, loaded into memory at startup and read during inference. Writes append and periodically flush to disk. Simple, fast, no dependencies.

The failure mode is obvious once you see it: during a write, if a read hits a partially flushed state, you get inconsistency. For a single-user pipeline running sequentially, this almost never surfaces. You'd have to be unlucky for a read to interleave with a write in a way that causes problems. Once there are concurrent callers, that probability stops being unlucky and becomes predictable.

The production backend is now PostgreSQL via Supabase. Writes go through transactions. Reads get a consistent snapshot. The alias table and the entity registry update atomically — either both change or neither does. A caller mid-request gets a consistent registry view regardless of what writes are in flight.

The switch is controlled by an environment variable (ER_REGISTRY_BACKEND). The application logic doesn't change, just the persistence layer. This separation made the transition straightforward: I could test both backends against the same code without restructuring anything.

The healthcheck

Railway handles deployments by routing traffic only after a service passes its healthcheck. The /health endpoint returns 200 when the API is ready to serve requests and the registry backend is reachable.

This matters in practice because startup isn't instantaneous. The service loads the model, initializes the Splink configuration, and verifies the backend connection before reporting healthy. Without an accurate healthcheck, Railway might route traffic to an instance that's running but not ready, which produces the kind of half-initialized state that generates confusing errors.

During a deploy, Railway keeps the old version serving traffic until the new one passes its healthcheck. No request reaches the new version before it's ready. This zero-downtime behavior is Railway's default — I didn't configure it specially — but it only works correctly if the healthcheck accurately reflects whether the service is ready.

The healthcheck has failed in two ways across different deployments: backend unreachable, and model initialization error. Both are things I'd rather catch at startup than discover mid-request. The healthcheck turned each into a failed deploy rather than a silent production problem.

Registry integrity at 47,853 entities

The registry currently holds 47,853 resolved entities and 47,883 aliases. Most entries are stable. Some are probably wrong.

Early in the project, when I was still calibrating the Splink threshold, the model was more permissive than it should have been. Some merges happened that were likely incorrect — entity strings that shared enough surface similarity to pass the threshold but were different companies. A few of those early-period decisions are still in the registry.

I know this in general. I don't know specifically which ones without re-running the full corpus against the current model. That re-run is on the list but hasn't happened yet.

What I have now is a review layer before new merges commit to the stable registry. Pairs that the model scores as probable matches but below a high-confidence threshold go into a pending state rather than being committed immediately. They get reviewed before joining the stable set. This doesn't fix the early errors already in the registry, but it stops new errors from accumulating at the same rate.

The production API serves only the stable registry. Pending pairs aren't exposed to external callers. If the model is uncertain, the caller gets a split decision. They can re-query later once additional evidence has accumulated and the pair has cleared review.

What "beta" actually means here

The last few posts in this series have mentioned "beta" without being specific. Here's what it actually implies:

The API is running. External callers are using it. I'm expanding access carefully rather than opening it wide.

It's not a prototype — the infrastructure decisions described above are real, the registry has nearly 48k entities built from actual article processing, and the resolver has been running reliably for months. It's also not a mature product with SLAs, a dedicated support tier, or uptime commitments beyond what Railway's infrastructure provides.

If you have an entity resolution problem — corporate name disambiguation, customer record deduplication, knowledge graph construction from heterogeneous sources — and want to try the service, there's a form at hannune.ai. I'll respond directly.

Next: the final part of this series wraps up the full arc and looks at where the same five-step pattern — DB limits, knowledge graph, ER bottleneck, direct implementation, cloud deployment — shows up outside investing graphs.

Built on Splink for probabilistic record linkage. Part 1 is here. Part 2 is here. Part 3 is here. Part 4 is here.

Building an investing knowledge graph, part 4: building the resolver

Tae Kim — Tue, 01 Sep 2026 02:37:00 +0000

Building an investing knowledge graph, part 4: building the resolver

Part 3 ended with a question I left open: how does the threshold actually get set, and what happens to the registry when new articles keep coming in? That's what this one covers.

The cost of getting it wrong in both directions

Before I touch thresholds, it's worth being specific about what failing in each direction costs.

A false merge combines two distinct entities into one node. In the Samsung SDI case from part 3, that would mean battery-supply disruptions show up when you traverse from the semiconductor business. The graph gives you an answer. The answer is wrong. You don't necessarily know it's wrong without already knowing the answer, which defeats the point.

A false split keeps the same entity as two separate nodes. "Samsung Electronics" and "the largest memory chipmaker in the world" stay disconnected. Edges pile up on each independently. A traversal from one doesn't reach the other. The graph gives you a partial answer. You lose coverage.

These aren't symmetric. A false merge injects noise that's hard to detect. A false split just means a disconnected node — you miss some connections, but you don't get fabricated ones.

So I set the threshold conservatively. Pairs below a high confidence mark stay split. Some real aliases end up never linking. That's the tradeoff I chose: lower recall, higher precision. For a graph I'm using to make judgments about which news matters, a confidently wrong edge is worse than a missing one.

What the endpoint does

The resolution service exposes a /v1/splink-pairs endpoint. It takes a list of candidate entity mention strings and returns a score for each pair, along with whether that pair crosses the registry threshold.

A minimal request looks like this:

POST /v1/splink-pairs
{
  "candidates": [
    "Samsung Electronics Co.",
    "the largest memory chipmaker in the world",
    "Samsung SDI",
    "TSMC"
  ]
}

The response returns a score matrix for pairs that the model considers worth evaluating — not every combination, just the ones above a blocking threshold that filters out obviously unrelated pairs before the full model runs.

{
  "pairs": [
    {
      "left": "Samsung Electronics Co.",
      "right": "the largest memory chipmaker in the world",
      "match_probability": 0.96,
      "decision": "match",
      "canonical_id": "company:samsung_electronics"
    },
    {
      "left": "Samsung Electronics Co.",
      "right": "Samsung SDI",
      "match_probability": 0.12,
      "decision": "split",
      "canonical_id": null
    }
  ]
}

The caller gets a decision (match or split) and the canonical entity ID when there's a match. If the match is against a known registry entry, the alias gets recorded. If it's a new pair the model hadn't seen before, that pair gets added to the evidence set for future model updates.

How the registry grows

When the investing knowledge graph pipeline processes a new article, it extracts entity mentions and runs them through the resolver. Three things can happen:

Known alias. The string matches an existing entry in the alias table. Lookup is fast, no model call needed. The mention gets written to the graph under the existing canonical ID.

Unknown mention, matches existing entity. The string isn't in the alias table, but the model scores it as a probable match against an existing entity. The alias gets added to the registry. Future articles that use the same string skip the model call.

Genuinely new entity. The model doesn't find a confident match against anything in the registry. A new canonical entry gets created. It starts small — one mention, no resolved aliases — and accumulates evidence as future articles mention the same company.

The registry currently has 47,853 resolved entities and 47,883 aliases. A lot of those started as single-mention nodes. Some have since merged as more articles confirmed the connection.

A few early decisions are probably still wrong. In the first batches I was more aggressive with merging, before I tightened the threshold. There are likely some nodes that should be split. I know this in general; I don't know specifically which ones without re-running the full corpus against the current model, which I haven't done.

What Splink is doing under the hood

Splink is the open source probabilistic record linkage library the model is built on. It uses DuckDB as the computation backend for the pair scoring, which handles the candidate generation and blocking step — filtering the space of possible pairs before running the full model.

For corporate entity mentions, the features that ended up mattering:

String similarity on the canonical name: catches abbreviations and common shorthand
Alias coverage: once a surface form is in the registry, future instances match by lookup rather than model score — this is how "the largest memory chipmaker in the world" eventually becomes reliable without its string similarity to "Samsung Electronics" ever improving
Token overlap on co-occurring named entities within the same article: an article about DRAM yields tends to mention different companies than an article about battery chemistry
Base rate weighting: a rare entity (one mention, no confirmed aliases) shouldn't get absorbed into a high-frequency entity just because they share a token

Splink learns the feature weights from labeled pairs. The training set was several hundred manually verified matches and non-matches from the first two thousand articles. Not large. But I had enough confirmed Samsung/Samsung SDI pairs to get the context features weighted correctly.

The point where this became a service

Somewhere around the third project where I had the same entity resolution problem — merging customer records from two systems, with the same fragmentation-versus-false-merge tradeoff — I stopped treating this as a per-project function and wrapped it into a standalone FastAPI service.

The knowledge graph pipeline now calls it over HTTP. Other things call it the same way. The registry is shared across callers. A match that one pipeline discovers helps every other caller that sees the same entity later.

That service is what I'm calling ER API. It runs on Railway, it's live, and the registry it's backing is the same one that's kept the investing knowledge graph from turning into a tangle of phantom nodes.

Next: what it takes to keep this running in production — the parts that only showed up after the first real caller wasn't me.

Built on Splink for probabilistic record linkage. Part 1 is here. Part 2 is here. Part 3 is here.