Entities

Almost every question worth asking about markets is about something — a company, a person, a commodity, a country, an institution. Entities are how Ultralayer makes that "something" a queryable object rather than a string-matching exercise.

The principle: identity over strings

"Tesla", "Tesla, Inc.", "TSLA", and "the EV maker led by Elon Musk" are one identity wearing four costumes. Text search treats them as four different things; an entity model treats them as one. Every entity in Ultralayer has a canonical name — one authoritative form (Tesla, Inc., Federal Reserve, Brent Crude) that acts as its stable identifier across the platform. Filter the Wire by an entity, pull a dossier, read mentions on a wire item — the same canonical name means the same real-world identity everywhere.

Entities are deliberately broader than a ticker universe. The things that move markets are not all listed companies:

Grounded mentions, not keyword hits

When content is ingested, the entities it discusses are extracted and grounded against the registry of known identities. A mention is a structured judgment, not a substring match:

• Relevance — is this entity the primary subject of the item, a significant participant, or a passing mention? Filtering on relevance is the difference between "news about Tesla" and "news that says the word Tesla."
• Mention-level sentiment — how the item treats this entity specifically, from −1 to 1. One headline can be positive for the acquirer and negative for the target; per-mention sentiment captures that, where a single document-level score cannot.

This is what powers precise monitoring: "items where Apple is a primary subject with strongly negative sentiment" is a three-filter query, not an NLP project.

How names resolve

Entity inputs match the canonical name, case-insensitively and exactly. The behavior to internalize:

• Unknown names fail loudly. A name that doesn't resolve returns an error with suggestions — candidate canonical names to retry. Suggestions are hints, not confirmed identities.
• Tickers are not entity names. TSLA does not resolve. (One deliberate exception in vocabulary: development stakeholders are public companies identified by ticker — that surface speaks ticker, entity surfaces speak canonical name.)
• Short names can resolve to the wrong identity, silently. "Tesla" may match a different, sparse registry entry than "Tesla, Inc." — returning empty results rather than an error. This is the one trap worth memorizing.

The reliable workflow: never guess canonical names — copy them. Take canonical_name from a prior wire hit or a successful retrieve_entity call and reuse it exactly. For listed companies, fuller legal-style forms ("Apple Inc.", "Nvidia Corporation") are the safe default. Per-endpoint resolution details live in the capability pages: Wire entity filters, entity retrieval name resolution.

An evolving system

Entity systems are never finished — new identities appear daily, and deciding whether two names are the same real-world thing is a genuinely hard problem. Expect the registry and resolution behavior to keep improving: identities get merged as duplicates are found, and resolution gets more forgiving over time. Two practical consequences today:

• Occasionally you'll see near-duplicate identities side by side (e.g. a company under two name variants in co-mention lists). Collapse them when briefing.
• The canonical-name-copying workflow above is the stable path through any rough edges — it will keep working as resolution improves around it.