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.
01 · Sources and storage
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.
GLEIF LEI records, registration history and accounting relationships
SEC 13F, 13D/G, Forms 3/4/5, N-PORT, Form ADV and EDGAR submissions
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.
02 · Entity resolution
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.
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 decision03 · Canonical entities and graph
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.
04 · Runtime
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.
05 · The research loop
The model chooses tools. The tools create the evidence.
- 1Plan a narrow lookup
The model sees tool schemas and chooses a search, profile, hierarchy, filing or connection call.
- 2Call the MCP server
The orchestrator talks to a standalone process over stdio. Each tool is a thin wrapper around tested core logic.
- 3Store evidence and facts
Every result records its source, criteria, record references and reproducible query hash. Numeric facts include a document address.
- 4Continue or submit
The model can investigate further, but its final citations are restricted to evidence IDs produced in this conversation.
- 5Verify 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.
06 · The answer gate
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.
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.
07 · Honest limits
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.
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.
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.
Manager, beneficial owner, accounting parent and person with significant control answer different legal and regulatory questions.