Event Model Overview - ViceWire Documentation

ViceWire does not treat an article as a single undifferentiated record. It treats the article as a source document that can produce one or more company-specific event objects.

Levels in the model

At a high level, the external payload has three parts:

entity

entity identifies the security the events relate to.

media_item

media_item keeps article-level context such as publication metadata, company relevance signals, and document-level metrics.

events

events is the event-level output. This is where the article is decomposed into one or more structured events for the given entity.

Example Shape

Example payload shape for entity, media_item, events

{
  "entity": {
    "security_name": "Apple",
    "ticker": "AAPL",
    "mic": "IEXG",
    "cik": "320193",
    ...
  },
  
  "media_item": {
    "date_published": "2026-01-16T22:42:00Z",
    "domain_category": "industry_specialist",
    "domain_tier": 2,
    "entity_count": 33,
    "mentioned_in_title": true,
    ...
  },
  
  "events": [
    {
      "event_family": "legal_regulatory",
      "event_sub_types": [{ "sub_type": "consumer_commercial_practices" }],
      "event_stage_statuses": [{ "stage_status": "negotiated_resolution" }],
      "event_family_metadata": {...}
      ...
      ...
    }
  ]
}

How one article becomes one or more event objects

The model identifies which Level 1 (L1) event families are actually present in the article. If one family is confirmed, the article produces one event object. If multiple families are confirmed, it produces multiple event objects. In simple terms, for each materially relevant entity, ViceWire applies the same event-model workflow:

1. Start with one article

Begin with a single article as the source input and identify all relevant entities.

2. Check entity relevance

Determine whether the entity is a core focus or only mentioned in passing.

3. Identify event families

Identify the confirmed event families present in the article.

4. Build event objects

Build one event object for each confirmed family.

5. Return grouped results

Return those event objects under the same article-level container.

What happens when multiple entities are detected

ViceWire does not assume that every detected entity should produce output. It first determines which entities are materially relevant to the article. If more than one entity is materially relevant, the same article can produce separate entity-scoped outputs. The output structure stays the same in each case: a different entity, its own media_item context, and its own set of events interpreted relative to that entity. That matters because the same article can imply different event interpretations for different companies. Keeping outputs entity-scoped avoids collapsing those interpretations into one mixed record.

What each event object contains

Although event families differ, many event objects share a common top-level structure. This structure is outlined below:

event_family

event_family is the primary company-specific event category, such as product, legal, partnership, supply-chain, demand-related coverage, workforce labour, security incidents, services content reception, and many more.The family is the anchor for the rest of the event object. It determines which subtype, stage logic, and family-specific metadata to collect.

timing

timing describes how the event is anchored in time relative to the article. For example, it helps distinguish a newly reported development from a historical event that is only being referenced as background, or an older matter that has become relevant again because of a new step, ruling, or update.

editorial_form

editorial_form describes how the article is framed, for example whether the piece is reporting a current development or analyzing past earnings results.

timing and editorial_form together help distinguish a live development from background, retrospective, or commentary-style coverage. That matters because a newly reported event vs an article discussing a historical event are not equally useful in downstream models.In many cases, older events are already widely known and more likely to be priced in, while a new procedural step, announcement, or operational change may carry fresher information.Keeping timing and editorial form explicit helps the system separate potentially incremental developments from background context or retrospective analysis.

event_sub_types

event_sub_types is how the model distinguishes different underlying mechanisms inside the same broad family. It keeps the event object more specific than an L1 category alone.For example, two events may both sit under the same parent Product family, but describe very different types of product developments, such as a new feature announcement versus a product quality issue. Subtype preserves that distinction so the event object is more precise than the parent L1 family alone.

event_stage_statuses

event_stage_statuses describes where the event sits in its lifecycle.This matters because different stages can carry different market meanings. In legal and corporate event studies, early procedural steps often increase uncertainty, while later stages such as settlements or final decisions can clarify outcomes. ViceWire applies that principle across event families distinguishing whether an event is still emerging, formally announced, in progress, escalated, resolved, or otherwise at a different point in its lifecycle.

event_family_metadata

event_family_metadata captures the structured details that make the event usable beyond a high-level label.This is where the model stores the event attributes that are materially relevant to interpretation, filtering, and downstream use. Depending on the family, that can include things like direction of change, dates, counterparties, obligations, remedy type, monetary amounts, scope, and event-linked geography when those details are explicitly supported by the source.

affected_business_surface

affected_business_surface maps the event to the part of the security that is directly implicated.This layer answers a different question from event family. Event family says what kind of event this is. Affected business surface says where in the Company or Entity the event lands.Using Apple as an example, a partnership event might land on apple_intelligence_and_siri if the relationship is about AI capability enablement, while a supply-chain or manufacturing event might land on mac if the issue is tied to MacBook production. The same broad event family can therefore map to very different Apple surfaces depending on what is actually affected.That makes it easier to connect events to the business areas that may matter for revenue, costs, operations, or segment-level performance, and it lets downstream users filter events by the part of the business they care about.

Affected Business Surface

Read more about Affected Business Surface.

finbert

finbert contains event-linked tone analytics computed from evidence tied to each confirmed event family.FinBERT is a finance-specific Natural Language Processing (NLP) model designed to analyze sentiment in financial text.This is not the only sentiment or directional layer in the model. It is additive to other directional or impact-oriented fields already present elsewhere, such as impact_direction and primary_impact_channel in relevant event families.The finbert field should therefore be read as one input into sentiment interpretation, not the only one.

​Levels in the model

​Example Shape

​How one article becomes one or more event objects