Entity intelligenceOpen research
Back to research

How it works · Technical guide

From a messy name to a defensible answer.

Institutional records disagree by default. The same organisation can appear as a legal entity, investment manager, filer, fund series or beneficial owner, with a different name and identifier in every system. This platform connects those records without erasing what each source actually claims.

ArchitectureEntity resolutionEvidence systems10 min read

Each source keeps its own meaning all the way in.

There is no universal import script. Every source owns its raw parser, Pydantic validation model, Arrow schema and ingestion pipeline. A malformed row fails at that boundary instead of quietly entering the entity layer.

Legal identity

GLEIF LEI records, registration history and accounting relationships

Regulatory filings

SEC 13F, 13D/G, Forms 3/4/5, N-PORT, Form ADV and EDGAR submissions

Registers and mappings

Companies House, FFIEC NIC, SEC series and class records, and OpenFIGI

Clean records land in Parquet, the build-time system of record. Crosswalk decisions, human reviews, canonical identifiers and graph facts are all reproducible from there. OpenSearch is a serving layer shaped for fast reads, not a second source of truth.

The serving layer is disposable: rebuilding it from Parquet must lose nothing.

Matching is a decision pipeline, not a similarity lookup.

A source name first retrieves a small candidate set from millions of legal entities. Retrieval considers full, core and compact name forms. Country is normally a soft signal because real filings often contain stale or incorrect jurisdictions.

Pure comparison functions then produce named signals: name similarity, address and postcode agreement, jurisdiction, registration identifiers, fund number, and master or feeder conflicts. Configuration-owned weights turn those signals into a score. No learned model hides why a candidate gained or lost points.

A high score asks whether one candidate looks right. The runner-up gap asks whether another looks almost as right.

The final decision uses both the top score and the gap to the runner-up. A single strong candidate can become AUTO_MATCH. Two nearly equal candidates become REVIEW. Weak evidence becomes UNMATCHED. Abstaining is a feature: a confident wrong entity is worse than no match.

retrieval/candidates.pyBuild candidate querymatching/features.pyCompute comparison signalsmatching/scoring.pyApply configured weightsmatching/decisions.pyScore and gap decision

Identity joins records. Typed edges preserve claims.

The canonical entity layer gives each resolved institution one internal entity record and attaches every external identifier with its source and confidence. A CIK, LEI, CRD number and company number can point to the same entity without pretending those identifier systems are interchangeable.

The knowledge graph keeps legal entities, fund series, share classes, securities and people as separate node types. It also keeps every relationship type distinct:

Accounting parent
GLEIF consolidation relationship
Bank control
FFIEC NIC regulatory control
Beneficial owner
Schedule 13D/G ownership above the reporting threshold
Significant control
Companies House persons with significant control
Reported position
SEC 13F investment discretion, not ownership

This prevents two damaging shortcuts: attaching a security identifier to its issuer as though they were the same node, and treating an investment position as corporate ownership. Every graph fact retains a document ID and locator back to the record that asserted it.

Search and agent mode are different interfaces over the same records.

Search is the direct path. The API retrieves ranked entity candidates, selects the first result by default, and opens its pre-shaped profile beside the list. The profile includes identity, lineage, identifiers, resolution decisions, typed connections and source-specific activity.

Agent mode is the investigative path. It can chain several lookups, compare records and explain what the evidence does or does not establish. It does not get a private database shortcut. Its MCP tools call the same core entity, graph and filing logic used by the API and command line.

The interface changes. The identity and relationship logic underneath it does not.

The model chooses tools. The tools create the evidence.

  1. 1
    Plan a narrow lookup

    The model sees tool schemas and chooses a search, profile, hierarchy, filing or connection call.

  2. 2
    Call the MCP server

    The orchestrator talks to a standalone process over stdio. Each tool is a thin wrapper around tested core logic.

  3. 3
    Store evidence and facts

    Every result records its source, criteria, record references and reproducible query hash. Numeric facts include a document address.

  4. 4
    Continue or submit

    The model can investigate further, but its final citations are restricted to evidence IDs produced in this conversation.

  5. 5
    Verify the finished answer

    A separate decision model checks grounding, contradiction, citation support and scope against the complete tool transcript.

The live interface streams these stages as server-sent events. Tool calls and results appear while the run is active; the finished answer replaces the activity feed while the evidence rail remains available.

The model cannot type a number into the final answer.

Tools return addressed Fact objects. The draft refers to them with placeholders such as {{f:fact_id}}. Before accepting the answer, the submission gate groups every referenced fact by its originating tool call, repeats those calls and checks that each fact returns with the same value.

Citations prove where a claim came from. Fact replay proves the value still comes back.

Only then does the renderer replace placeholders with values. Computed changes and percentages must come from registered formulas and carry their input facts. This separates fluent writing from numerical authority.

Absence from the graph is not proof of absence.

Coverage follows the records that were available, ingested and successfully linked for a specific date. Sources can lag, disagree or omit relationships. The interface exposes dates, warnings and provenance so a user can judge that boundary.

SEC 13F is not a complete portfolio.

It covers certain reportable US equity securities at a quarterly date. It excludes shorts, many derivatives, non-US securities, private investments and positions below reporting thresholds.

A match score is not probability.

It is a deterministic weighted signal whose contributions can be inspected. Decision thresholds and the runner-up gap determine whether the system resolves or abstains.

Relationship words are source-specific.

Manager, beneficial owner, accounting parent and person with significant control answer different legal and regulatory questions.