> ## Documentation Index
> Fetch the complete documentation index at: https://vicewire.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Event Model Overview

> How ViceWire turns one article into one or more company-specific structured event objects.

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:

<ResponseField name="entity">
  `entity` identifies the security the events relate to.
</ResponseField>

<ResponseField name="media_item">
  `media_item` keeps article-level context such as publication metadata, [company relevance signals](core-concepts/entity-relevance-signals), and document-level metrics.
</ResponseField>

<ResponseField name="events">
  `events` is the event-level output. This is where the article is decomposed into one or more structured events for the given entity.
</ResponseField>

### Example Shape

```json Example payload shape for entity, media_item, events lines theme={null}
{
  "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:

<CardGroup cols={2}>
  <Card title="1. Start with one article">
    Begin with a single article as the source input and identify all relevant entities.
  </Card>

  <Card title="2. Check entity relevance">
    Determine whether the entity is a core focus or only mentioned in passing.
  </Card>

  <Card title="3. Identify event families">
    Identify the confirmed event families present in the article.
  </Card>

  <Card title="4. Build event objects">
    Build one event object for each confirmed family.
  </Card>

  <Card title="5. Return grouped results">
    Return those event objects under the same article-level container.
  </Card>
</CardGroup>

## 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:

<ResponseField name="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.
</ResponseField>

<ResponseField name="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.
</ResponseField>

<ResponseField name="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.
</ResponseField>

<Info>
  `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.
</Info>

<ResponseField name="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.
</ResponseField>

<ResponseField name="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.
</ResponseField>

<ResponseField name="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](/docs/geography-data) when those details are explicitly supported by the source.
</ResponseField>

<ResponseField name="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.

  <Card title="Affected Business Surface" colorLight="#FFFDA8" colorDark="#407272" icon="arrow-up-right-from-square" horizontal href="/docs/business-impact-mapping">
    Read more about Affected Business Surface.
  </Card>
</ResponseField>

<ResponseField name="finbert">
  `finbert` contains event-linked tone analytics computed from evidence tied to each confirmed event family.

  [FinBERT](https://huggingface.co/ProsusAI/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.

  <Card title="Directional Layers" colorLight="#FFFDA8" colorDark="#407272" icon="arrow-up-right-from-square" horizontal href="/docs/directional-layers">
    Read more about Directional Layers.
  </Card>
</ResponseField>