Anotação de Eventos

Anote estruturas de eventos N-árias no Potato com gatilhos de evento, argumentos tipados e papéis de entidades para tarefas de extração de informação e detecção de eventos no estilo ACE.

A anotação de eventos permite criar estruturas de eventos N-árias para tarefas de extração de informação. Os eventos são compostos por um span de gatilho (a palavra ou expressão que indica o evento) e spans de argumento (spans de entidade com papéis semânticos tipados).

Esse tipo de anotação é usado com frequência em extração de informação, detecção de eventos, rotulação de papéis semânticos e construção de grafos de conhecimento.

Configuração Básica

A anotação de eventos exige que um esquema de anotação de span seja definido primeiro, fornecendo os spans de entidade usados como gatilhos e argumentos.

yaml

annotation_schemes:
  # Step 1: Define entity spans
  - annotation_type: span
    name: entities
    description: "Label entities in the text"
    labels:
      - name: PERSON
        color: "#3b82f6"
      - name: ORGANIZATION
        color: "#10b981"
      - name: LOCATION
        color: "#f59e0b"
      - name: WEAPON
        color: "#ef4444"
      - name: EVENT_TRIGGER
        color: "#8b5cf6"
        tooltip: "Words indicating events"
 
  # Step 2: Define event types and arguments
  - annotation_type: event_annotation
    name: events
    description: "Annotate events with triggers and arguments"
    span_schema: entities
    event_types:
      - type: "ATTACK"
        color: "#dc2626"
        trigger_labels: ["EVENT_TRIGGER"]
        arguments:
          - role: "attacker"
            entity_types: ["PERSON", "ORGANIZATION"]
            required: true
          - role: "target"
            entity_types: ["PERSON", "ORGANIZATION", "LOCATION"]
            required: true
          - role: "weapon"
            entity_types: ["WEAPON"]
            required: false

Opções de Configuração

Tipos de Evento

Cada tipo de evento define:

Propriedade	Tipo	Obrigatório	Descrição
`type`	string	Sim	Nome do tipo de evento (ex.: "ATTACK", "HIRE")
`color`	string	Não	Cor para visualização (padrão: atribuída automaticamente)
`trigger_labels`	list	Não	Rótulos de span permitidos como gatilhos (vazio = qualquer span)
`arguments`	list	Sim	Lista de definições de argumento

Argumentos

Cada argumento define:

Propriedade	Tipo	Obrigatório	Descrição
`role`	string	Sim	Nome do papel semântico (ex.: "attacker", "target")
`entity_types`	list	Não	Rótulos de span permitidos para este papel (vazio = qualquer span)
`required`	boolean	Não	Se o argumento precisa ser preenchido (padrão: false)

Exibição Visual

yaml

visual_display:
  enabled: true           # Show arc visualization (default: true)
  arc_position: above     # Position of arcs: "above" (default)
  show_labels: true       # Show role labels on arcs (default: true)

Fluxo de Trabalho

Crie os spans de entidade: anote os spans de entidade usando a ferramenta de anotação de span (clique e arraste para selecionar o texto e depois escolha um rótulo)
Selecione o tipo de evento: clique no botão de um tipo de evento (ex.: "ATTACK") para entrar no modo de criação de evento
Selecione o gatilho: clique em um span para defini-lo como o gatilho do evento. Se trigger_labels estiver configurado, apenas spans com rótulos correspondentes podem ser selecionados
Atribua os argumentos: para cada papel de argumento, clique no botão do papel para ativá-lo e depois clique em um span para atribuí-lo. Os argumentos obrigatórios precisam ser preenchidos antes que o evento possa ser criado
Crie o evento: quando todos os argumentos obrigatórios estiverem preenchidos, clique em "Create Event" para salvar
Visualize os eventos: os eventos criados aparecem na seção "Existing Events" com seus gatilhos e argumentos listados

Formato dos Dados

Entrada

A anotação de eventos funciona com qualquer formato de dados baseado em texto:

json

[
  {
    "id": "event_1",
    "text": "John attacked the building with a rifle."
  }
]

Saída

Os eventos são armazenados com a seguinte estrutura:

json

{
  "event_annotations": [
    {
      "id": "event_abc123",
      "schema": "events",
      "event_type": "ATTACK",
      "trigger_span_id": "span_xyz789",
      "arguments": [
        {"role": "attacker", "span_id": "span_def456"},
        {"role": "target", "span_id": "span_ghi012"},
        {"role": "weapon", "span_id": "span_jkl345"}
      ],
      "properties": {
        "color": "#dc2626",
        "trigger_text": "attacked",
        "trigger_label": "EVENT_TRIGGER"
      }
    }
  ]
}

Exibição Visual

A visualização em arcos mostra:

Um hub (círculo preenchido) na posição do gatilho
Raios (setas) conectando cada argumento
Rótulos de papel em cada raio
Os eventos têm cores por tipo

Vários eventos são empilhados verticalmente para evitar sobreposição.

Exemplo Completo

yaml

annotation_schemes:
  - annotation_type: span
    name: entities
    description: "Label entities in the text"
    labels:
      - name: PERSON
        color: "#3b82f6"
      - name: ORGANIZATION
        color: "#10b981"
      - name: LOCATION
        color: "#f59e0b"
      - name: WEAPON
        color: "#ef4444"
      - name: EVENT_TRIGGER
        color: "#8b5cf6"
 
  - annotation_type: event_annotation
    name: events
    description: "Annotate events"
    span_schema: entities
    event_types:
      - type: "ATTACK"
        color: "#dc2626"
        trigger_labels: ["EVENT_TRIGGER"]
        arguments:
          - role: "attacker"
            entity_types: ["PERSON", "ORGANIZATION"]
            required: true
          - role: "target"
            entity_types: ["PERSON", "ORGANIZATION", "LOCATION"]
            required: true
          - role: "weapon"
            entity_types: ["WEAPON"]
            required: false
 
      - type: "HIRE"
        color: "#2563eb"
        trigger_labels: ["EVENT_TRIGGER"]
        arguments:
          - role: "employer"
            entity_types: ["ORGANIZATION"]
            required: true
          - role: "employee"
            entity_types: ["PERSON"]
            required: true
 
      - type: "TRAVEL"
        color: "#059669"
        trigger_labels: ["EVENT_TRIGGER"]
        arguments:
          - role: "traveler"
            entity_types: ["PERSON"]
            required: true
          - role: "destination"
            entity_types: ["LOCATION"]
            required: true
          - role: "origin"
            entity_types: ["LOCATION"]
            required: false

Boas Práticas

Use nomes de tipo descritivos - escolha nomes de tipo de evento claros e sem ambiguidade que reflitam o significado semântico
Restrinja os gatilhos adequadamente - use trigger_labels para limitar quais spans podem ser gatilhos. Para eventos baseados em verbos, crie um rótulo "EVENT_TRIGGER" dedicado
Equilibre argumentos obrigatórios e opcionais - marque os argumentos centrais como obrigatórios, mas permita argumentos opcionais para contextos que nem sempre estão presentes
Use restrições de tipo de entidade - imponha restrições semânticas aos argumentos (ex.: um "attacker" deve ser PERSON ou ORGANIZATION)

Leitura Complementar

Anotação de Span - Necessária para definir spans de entidade
Ligação de Spans - Alternativa para relações binárias
Cadeias de Correferência - Para correferência de entidades

Para detalhes de implementação, consulte a documentação de origem.