Histórico de Anotações

Acompanhe cada ação de anotação no Potato com carimbos de data/hora, IDs de anotadores e histórico de versões — permitindo trilhas de auditoria completas, suporte a desfazer e detecção de alterações.

O Potato oferece um rastreamento abrangente de todas as ações de anotação com metadados de carimbo de data/hora de alta granularidade. Isso permite análise de desempenho, garantia de qualidade e trilhas de auditoria detalhadas.

Visão geral

O sistema de histórico de anotações rastreia:

Cada ação de anotação: Seleções de rótulos, anotações de trecho, entradas de texto
Carimbos de data/hora precisos: Carimbos do lado do servidor e do cliente
Metadados da ação: Usuário, instância, esquema, valores antigos/novos
Métricas de desempenho: Tempos de processamento, taxas de ação
Atividade suspeita: Padrões de atividade incomumente rápidos ou em rajada

Rastreamento de ações

Cada alteração de anotação é registrada como uma AnnotationAction com:

Campo	Descrição
`action_id`	UUID exclusivo para cada ação
`timestamp`	Carimbo de data/hora do lado do servidor
`client_timestamp`	Carimbo de data/hora do lado do navegador (se disponível)
`user_id`	Usuário que realizou a ação
`instance_id`	Instância sendo anotada
`action_type`	Tipo de ação realizada
`schema_name`	Nome do esquema de anotação
`label_name`	Rótulo específico dentro do esquema
`old_value`	Valor anterior (para atualizações/exclusões)
`new_value`	Novo valor (para adições/atualizações)
`span_data`	Detalhes do trecho para anotações de trecho
`server_processing_time_ms`	Tempo de processamento do servidor

Tipos de ação

O sistema rastreia estes tipos de ação:

add_label - Nova seleção de rótulo
update_label - Valor do rótulo alterado
delete_label - Rótulo removido
add_span - Nova anotação de trecho criada
update_span - Anotação de trecho modificada
delete_span - Anotação de trecho removida

Configuração

O rastreamento de histórico de anotações é ativado por padrão. Nenhuma configuração adicional é necessária.

Métricas de desempenho

O sistema calcula métricas de desempenho a partir do histórico de ações:

python

from potato.annotation_history import AnnotationHistoryManager
 
metrics = AnnotationHistoryManager.calculate_performance_metrics(actions)
 
# Returns:
{
    'total_actions': 150,
    'average_action_time_ms': 45.2,
    'fastest_action_time_ms': 12,
    'slowest_action_time_ms': 234,
    'actions_per_minute': 8.5,
    'total_processing_time_ms': 6780
}

Detecção de atividade suspeita

O sistema pode detectar padrões de anotação potencialmente problemáticos:

python

from potato.annotation_history import AnnotationHistoryManager
 
analysis = AnnotationHistoryManager.detect_suspicious_activity(
    actions,
    fast_threshold_ms=500,      # Actions faster than this are flagged
    burst_threshold_seconds=2   # Actions closer than this are flagged
)
 
# Returns:
{
    'suspicious_actions': [...],
    'fast_actions_count': 5,
    'burst_actions_count': 12,
    'fast_actions_percentage': 3.3,
    'burst_actions_percentage': 8.0,
    'suspicious_score': 15.2,
    'suspicious_level': 'Low'
}

Níveis de suspeita

Pontuação	Nível	Interpretação
0-10	Normal	Comportamento típico de anotação
10-30	Baixo	Algumas ações rápidas, provavelmente aceitável
30-60	Médio	Padrão notável, pode justificar revisão
60-80	Alto	Padrão preocupante, revisão recomendada
80-100	Muito alto	Provável problema de qualidade, revisão imediata

Referência da API

AnnotationAction

python

from potato.annotation_history import AnnotationAction
 
action = AnnotationAction(
    action_id="uuid-here",
    timestamp=datetime.now(),
    user_id="annotator1",
    instance_id="doc_001",
    action_type="add_label",
    schema_name="sentiment",
    label_name="positive",
    old_value=None,
    new_value=True
)
 
# Serialize to dictionary
data = action.to_dict()
 
# Deserialize from dictionary
action = AnnotationAction.from_dict(data)

AnnotationHistoryManager

python

from potato.annotation_history import AnnotationHistoryManager
 
# Create a new action with current timestamp
action = AnnotationHistoryManager.create_action(
    user_id="annotator1",
    instance_id="doc_001",
    action_type="add_label",
    schema_name="sentiment",
    label_name="positive",
    old_value=None,
    new_value=True
)
 
# Filter actions by time range
filtered = AnnotationHistoryManager.get_actions_by_time_range(
    actions,
    start_time=datetime(2024, 1, 1),
    end_time=datetime(2024, 1, 31)
)
 
# Filter actions by instance
instance_actions = AnnotationHistoryManager.get_actions_by_instance(
    actions, instance_id="doc_001"
)
 
# Calculate performance metrics
metrics = AnnotationHistoryManager.calculate_performance_metrics(actions)
 
# Detect suspicious activity
analysis = AnnotationHistoryManager.detect_suspicious_activity(actions)

Casos de uso

Garantia de qualidade

Monitore o comportamento dos anotadores para detectar problemas de qualidade:

python

for user_id in get_all_users():
    user_actions = get_user_actions(user_id)
    analysis = AnnotationHistoryManager.detect_suspicious_activity(user_actions)
 
    if analysis['suspicious_level'] in ['High', 'Very High']:
        flag_for_review(user_id, analysis)

Trilha de auditoria

Acompanhe as alterações para conformidade regulatória:

python

instance_actions = AnnotationHistoryManager.get_actions_by_instance(
    all_actions, "doc_001"
)
 
audit_log = [action.to_dict() for action in instance_actions]
with open("audit_doc_001.json", "w") as f:
    json.dump(audit_log, f, indent=2)

Análise de tempo

Entenda os padrões de tempo de anotação:

python

from collections import Counter
 
hours = Counter(action.timestamp.hour for action in all_actions)
print("Peak annotation hours:", hours.most_common(5))

Armazenamento de dados

O histórico de anotações é armazenado nos arquivos de estado do usuário:

text

output/
  annotations/
    user_state_annotator1.json  # Includes action history
    user_state_annotator2.json

Formato de exportação

As ações são serializadas com carimbos de data/hora ISO 8601:

json

{
  "action_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2024-01-15T10:30:45.123456",
  "user_id": "annotator1",
  "instance_id": "doc_001",
  "action_type": "add_label",
  "schema_name": "sentiment",
  "label_name": "positive",
  "old_value": null,
  "new_value": true,
  "server_processing_time_ms": 23
}

Boas práticas

Monitoramento regular: Verifique periodicamente os relatórios de atividade suspeita
Ajuste de limiares: Ajuste os limiares de detecção com base na complexidade da tarefa
Exporte backups: Exporte o histórico regularmente para armazenamento de longo prazo
Conformidade de privacidade: Considere políticas de retenção de dados para carimbos de data/hora

Leitura adicional

Painel de Administração - Visualize estatísticas de anotação
Rastreamento Comportamental - Rastreamento em nível de interação
Controle de Qualidade - Verificações de qualidade automatizadas

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