Historial de Anotaciones

Rastrea cada acción de anotación con marcas de tiempo para auditoría y análisis.

Historial de Anotaciones

Potato proporciona seguimiento completo de todas las acciones de anotación con metadatos de marcas de tiempo detallados. Esto permite análisis de rendimiento, aseguramiento de calidad y registros de auditoría detallados.

Resumen

El sistema de historial de anotaciones rastrea:

Cada acción de anotación: Selecciones de etiquetas, anotaciones de spans, entradas de texto
Marcas de tiempo precisas: Marcas de tiempo del servidor y del cliente
Metadatos de acciones: Usuario, instancia, esquema, valores anteriores/nuevos
Métricas de rendimiento: Tiempos de procesamiento, tasas de acción
Actividad sospechosa: Patrones de actividad inusualmente rápida o en ráfagas

Seguimiento de Acciones

Cada cambio de anotación se registra como un AnnotationAction con:

Campo	Descripción
`action_id`	UUID único para cada acción
`timestamp`	Marca de tiempo del servidor
`client_timestamp`	Marca de tiempo del navegador (si está disponible)
`user_id`	Usuario que realizó la acción
`instance_id`	Instancia siendo anotada
`action_type`	Tipo de acción realizada
`schema_name`	Nombre del esquema de anotación
`label_name`	Etiqueta específica dentro del esquema
`old_value`	Valor anterior (para actualizaciones/eliminaciones)
`new_value`	Nuevo valor (para adiciones/actualizaciones)
`span_data`	Detalles del span para anotaciones de span
`server_processing_time_ms`	Tiempo de procesamiento del servidor

Tipos de Acciones

El sistema rastrea estos tipos de acciones:

add_label - Nueva selección de etiqueta
update_label - Valor de etiqueta cambiado
delete_label - Etiqueta eliminada
add_span - Nueva anotación de span creada
update_span - Anotación de span modificada
delete_span - Anotación de span eliminada

Configuración

El seguimiento del historial de anotaciones está habilitado de forma predeterminada. No se requiere configuración adicional.

Métricas de Rendimiento

El sistema calcula métricas de rendimiento a partir del historial de acciones:

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
}

Detección de Actividad Sospechosa

El sistema puede detectar patrones de anotación 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'
}

Niveles de Sospecha

Puntuación	Nivel	Interpretación
0-10	Normal	Comportamiento de anotación típico
10-30	Bajo	Algunas acciones rápidas, probablemente aceptable
30-60	Medio	Patrón notable, puede requerir revisión
60-80	Alto	Patrón preocupante, se recomienda revisión
80-100	Muy Alto	Probable problema de calidad, revisión inmediata

Referencia de la 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

Aseguramiento de Calidad

Monitorea el comportamiento de los anotadores para detectar problemas de calidad:

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)

Registro de Auditoría

Rastrea cambios para cumplimiento regulatorio:

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álisis de Tiempo

Comprende los patrones de tiempo de anotación:

python

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

Almacenamiento de Datos

El historial de anotaciones se almacena en los archivos de estado del usuario:

text

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

Formato de Exportación

Las acciones se serializan con marcas de tiempo 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
}

Mejores Prácticas

Monitoreo regular: Revisa los reportes de actividad sospechosa periódicamente
Ajuste de umbrales: Ajusta los umbrales de detección según la complejidad de la tarea
Respaldos de exportación: Exporta el historial regularmente para almacenamiento a largo plazo
Cumplimiento de privacidad: Considera políticas de retención de datos para las marcas de tiempo

Lectura Adicional

Panel de Administración - Ver estadísticas de anotación
Seguimiento Conductual - Seguimiento a nivel de interacción
Control de Calidad - Verificaciones de calidad automatizadas

Para detalles de implementación, consulta la documentación fuente.