> ## Documentation Index > Fetch the complete documentation index at: https://avala.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Esquema de metadatos de secuencia > La etiqueta de resultado de cada secuencia, cómo se informa la validez técnica y cómo leer, escribir y exportar ambas Cada secuencia lleva dos tipos de metadatos separados: * **Validez técnica.** ¿La grabación es utilizable? Avala la informa a partir de los criterios de aceptación y los objetivos de calidad. Consulte la sección Validez técnica. * **Resultado de comportamiento.** ¿Qué hizo la persona o el robot, y la tarea tuvo éxito? Avala lo guarda como la **etiqueta de resultado** de la secuencia. Una secuencia puede ser técnicamente válida y aun así mostrar un fallo. Una secuencia fallida suele ser la más útil. Los dos ejes se mantienen separados, así que un filtro de datos limpios nunca descarta un fallo útil, y un filtro de éxito nunca oculta un sensor averiado. ## La etiqueta de resultado Cada secuencia tiene como máximo una etiqueta de resultado vigente. Cada escritura registra una nueva versión. Las versiones anteriores siguen disponibles en el historial de la etiqueta. ### Ejemplo Esta es la etiqueta de una demostración humana con un deslizamiento y una recuperación, tal como la devuelve `GET .../sequences//outcome/`: ```json theme={null} { "uid": "", "sequence_uid": "", "version": 2, "is_current": true, "outcome": "mistake_and_recovery", "progress": 1.0, "quality": 4, "speed": 3, "subtasks": [ { "label": "Load the plate into the lower rack", "start_ts": 0.0, "end_ts": 19.8, "outcome": "mistake_and_recovery" }, { "label": "Pull out the lower rack", "start_ts": 0.0, "end_ts": 6.2, "outcome": "expert_success" }, { "label": "Place the wet plate in a free slot", "start_ts": 6.2, "end_ts": 19.8, "outcome": "mistake_and_recovery" } ], "hand_actions": { "left": [ { "start_ts": 0.0, "end_ts": 6.2, "action": "pulling the lower rack out by its front edge", "object": "dishwasher rack", "verb": "pull", "contact": true }, { "start_ts": 6.2, "end_ts": 19.8, "action": "holding the rack steady", "object": "dishwasher rack", "verb": "hold", "contact": true } ], "right": [ { "start_ts": 6.2, "end_ts": 9.1, "action": "carrying the wet plate to the rack", "object": "plate", "verb": "carry", "contact": true }, { "start_ts": 9.1, "end_ts": 10.4, "action": "the plate slips out of the grasp", "object": "plate", "verb": null, "contact": false }, { "start_ts": 10.4, "end_ts": 14.7, "action": "regrasping the plate by its rim", "object": "plate", "verb": "grasp", "contact": true }, { "start_ts": 14.7, "end_ts": 19.8, "action": "placing the plate in a free slot", "object": "plate", "verb": "place", "contact": true } ] }, "mistake_type": "slip_during_place", "recovery_type": "regrasp", "failure_stage": "place", "autonomy_level": "human_demonstration", "model_version": "", "evaluation_membership": "train", "leakage_groups": { "location": "loc_8f2a", "object": "obj_set_31", "mechanism": "dishwasher_pull_rack_v2", "operator": "op_5c1e", "environment_family": "kitchen_galley" }, "source": "human", "source_metadata": {}, "labeled_by": "", "confidence": null, "created_at": "2026-09-30T17:42:11.204000Z", "updated_at": "2026-09-30T17:42:11.204000Z" } ``` Los valores ilustran la forma de la etiqueta. No describen una entrega real. ### Campos Todas las marcas de tiempo son segundos desde el inicio de la secuencia. | Campo | Tipo | Significado | | - | - | - | | `uid` | string | ID de esta versión de la etiqueta. Solo lectura. | | `sequence_uid` | string | La secuencia a la que pertenece la etiqueta. Solo lectura. | | `version` | integer | Versión de la etiqueta, empezando en 1. Cada escritura suma uno. Solo lectura. | | `is_current` | boolean | `true` para la versión vigente. Solo lectura. | | `outcome` | string | El resultado de comportamiento. Obligatorio. Consulte la sección Valores de resultado. | | `progress` | number o null | Progreso de la tarea, de 0 a 1. | | `quality` | integer o null | Calidad de ejecución, de 1 a 5. | | `speed` | integer o null | Velocidad de ejecución, de 1 a 5. | | `subtasks` | list | Rangos de tiempo etiquetados. Consulte la sección Subtareas. | | `hand_actions` | object | Flujos de acciones por mano, `left` y `right`. Consulte la sección Acciones de las manos. | | `mistake_type` | string | Su etiqueta para el tipo de error. Hasta 128 caracteres. Vacío si no se define. | | `recovery_type` | string | Su etiqueta para el tipo de recuperación. Hasta 128 caracteres. Vacío si no se define. | | `failure_stage` | string | Su etiqueta para la etapa en la que ocurrió el fallo. Hasta 128 caracteres. Vacío si no se define. | | `autonomy_level` | string | Quién tenía el control. Consulte la sección Nivel de autonomía. Vacío si no se define. | | `model_version` | string | La versión de la política o del modelo que controló el robot. Hasta 255 caracteres. Vacío para demostraciones humanas. | | `evaluation_membership` | string | `train`, `held_out_eval` o `none`. Vacío si no se define. Consulte la sección Pertenencia a evaluación. | | `leakage_groups` | object | IDs de grupo para mantener limpias las divisiones. Consulte la sección Grupos de fuga. | | `source` | string | Quién escribió la etiqueta: `human`, `model` o `imported`. Por defecto `human`. | | `source_metadata` | object | Procedencia de la importación. Consulte la sección Metadatos de origen. | | `labeled_by` | string o null | UID del usuario que escribió la versión. Solo se devuelve a quien puede editar el dataset. Solo lectura. | | `confidence` | number o null | Confianza del modelo, de 0 a 1. Solo se acepta cuando `source` es `model`. | | `created_at`, `updated_at` | string | Marcas de tiempo de la versión. Solo lectura. | `mistake_type`, `recovery_type` y `failure_stage` son texto libre. Use las etiquetas de la taxonomía de fallos de su programa para que las secuencias se agrupen con limpieza. ### Valores de resultado | Resultado | Significado | | - | - | | `expert_success` | La tarea está completa. La ejecución es fluida y a ritmo experto. | | `slow_success` | La tarea está completa. La ejecución es correcta y claramente más lenta que el ritmo experto. | | `partial_success` | Parte de la tarea está completa. No se alcanza el estado objetivo final. | | `mistake_and_recovery` | Ocurre un error, como un deslizamiento, un fallo de agarre o una colocación incorrecta. Quien actúa se recupera sin ayuda externa y completa la tarea. | | `intervention` | Una persona interviene para corregir o terminar la tarea. | | `unsafe` | La secuencia contiene una acción o un estado inseguro. | | `aborted` | El intento se detiene antes de completar la tarea, sin recuperación. | | `failure` | El intento termina y la tarea no se logra. | | `novel_strategy` | La tarea se resuelve de una forma válida que difiere de la estrategia habitual. | | `inefficient_strategy` | La tarea se resuelve con movimiento extra evitable, intentos repetidos o rodeos. | Cada subtarea puede llevar su propio resultado de la misma lista. ### Nivel de autonomía | Valor | Significado | | - | - | | `human_demonstration` | Una persona realiza la tarea. | | `teleoperation` | Una persona controla el robot a distancia. | | `autonomous` | El robot funciona con su política. | | `shared_autonomy` | La política y una persona comparten el control. | | `intervention` | Una persona toma el control de la política durante la secuencia. | ### Subtareas Cada subtarea es `{label, start_ts, end_ts, outcome}`. | Campo | Regla | | - | - | | `label` | Descripción de la subtarea en lenguaje natural. Obligatorio. De 1 a 500 caracteres. | | `start_ts`, `end_ts` | Números finitos, 0 o más. `end_ts` es al menos `start_ts`. | | `outcome` | Un valor de resultado, o `null`. | Una etiqueta contiene como máximo 256 subtareas. La lista debe estar ordenada por `start_ts`. Dos subtareas cualesquiera son disjuntas o una contiene por completo a la otra, como una fase y sus pasos. Los extremos que se tocan cuentan como disjuntos. Un solapamiento parcial se rechaza. Cuando dos subtareas empiezan al mismo tiempo, ponga primero la que contiene a la otra. ### Acciones de las manos `hand_actions` contiene dos flujos independientes, `left` y `right`. Cada elemento describe lo que hace una mano durante un rango de tiempo. | Campo | Regla | | - | - | | `start_ts`, `end_ts` | Números finitos, 0 o más. `end_ts` es al menos `start_ts`. | | `action` | Descripción de la acción en lenguaje natural. Obligatorio. De 1 a 500 caracteres. | | `object` | El objeto sobre el que trabaja la mano. Opcional. Hasta 255 caracteres. | | `verb` | Un verbo corto para la acción. Opcional. Hasta 64 caracteres. | | `contact` | `true` cuando la mano toca el objeto, `false` cuando no lo toca, `null` cuando se desconoce. Solo se aceptan booleanos JSON. | * Dentro de una mano, los elementos se ordenan por `start_ts` y no deben solaparse. Un elemento empieza en el final del anterior o después. Tocarse está permitido. * Las dos manos se solapan libremente. * Cada mano contiene como máximo 3.600 elementos. Eso es una hora a una etiqueta por segundo. * `left` y `right` son las únicas claves. Puede omitir cualquiera de ellas. Una mano omitida se guarda como una lista vacía. * Un `object` o `verb` vacío se guarda como `null`. Cada elemento guardado tiene los seis campos. ### Duración de la secuencia Cuando Avala conoce la duración de la secuencia, cada `end_ts` de subtarea y cada `end_ts` de acción de mano debe ser como máximo la duración más 1 segundo. El segundo extra admite etiquetas escritas a una por segundo. Avala conoce la duración cuando la secuencia tiene exactamente un archivo MCAP extraído con una duración registrada. Para las demás secuencias, la verificación se omite. ### Pertenencia a evaluación `evaluation_membership` asigna la secuencia a una división: | Valor | Significado | | - | - | | `train` | La secuencia puede usarse para entrenamiento. | | `held_out_eval` | La secuencia pertenece a un conjunto de evaluación reservado. Manténgala fuera del entrenamiento. | | `none` | La secuencia no está en ninguna de las dos divisiones. | Avala define `held_out_eval` en las secuencias de cada cohorte de evaluación. Esas secuencias nunca aparecen en una release de entrenamiento. Consulte [Evaluación](/docs/es/fleet-learning/evaluation.md). ### Grupos de fuga Los grupos de fuga evitan que casi duplicados queden a ambos lados de una división entre entrenamiento y evaluación. `leakage_groups` acepta estas claves, cada una con un ID de grupo de hasta 255 caracteres: | Clave | Agrupa secuencias que comparten | | - | - | | `location` | La misma casa, sitio o habitación. | | `object` | El mismo conjunto de objetos físicos. | | `mechanism` | La misma unidad de electrodoméstico o mecanismo. | | `operator` | El mismo recolector o teleoperador. | | `environment_family` | El mismo tipo de entorno y distribución, como una cocina en línea. | Cualquier otra clave se rechaza. Cada clave es opcional. Avala construye las cohortes de evaluación de modo que ningún valor de grupo de una cohorte aparezca en ninguna release de entrenamiento. Usted puede dividir sus propios datos de la misma forma: reserve por grupo, nunca por secuencia aleatoria. Los IDs de grupo de Avala son seudónimos, así que puede agrupar y dividir sin saber quién ni dónde. ### Metadatos de origen `source_metadata` registra de dónde vino una etiqueta importada, por ejemplo `{"importer": "...", "run_id": "...", "task": "...", "log_path": "..."}`. * Es un objeto plano con como máximo 20 claves. * Cada clave tiene de 1 a 64 caracteres. * Cada valor es un string de hasta 512 caracteres, un número finito o un booleano. * Los objetos anidados, las listas y los valores `null` se rechazan. ### Cómo funcionan las escrituras * Una escritura reemplaza la etiqueta vigente por completo y registra una nueva versión. Cualquier campo opcional que omita se guarda sin definir. No se copia de la versión anterior. * Escribir requiere acceso de edición al dataset. Leer requiere el mismo acceso que leer la secuencia, incluidos los datasets públicos. * `confidence` se rechaza salvo que `source` sea `model`. * Leer una secuencia sin etiqueta devuelve `404`. ## Validez técnica La validez técnica no forma parte de la etiqueta de resultado. Avala la informa desde el motor de aceptación y desde los objetivos de calidad, y no tiene un esquema JSON propio. **Criterios de aceptación.** Cada captura de una campaña de captura recibe un veredicto automático: `accept`, `quarantine` o `reject`. El veredicto proviene de estos criterios: | Criterio | Qué verifica | | - | - | | `capture_health` | El archivo MCAP se valida y los canales que exige la campaña están presentes. | | `frame_rate` | La tasa de fotogramas de la cámara se mantiene a lo largo del clip, sin una caída sostenida. | | `completeness` | La duración se acerca a la que pidió la campaña. | | `framing` | Las manos están visibles durante suficiente parte del tiempo que observó el detector. | | `shake` | La cámara no tiembla durante la mayor parte del clip. | Cada criterio informa `pass`, `fail`, `insufficient_evidence` o `skipped`. Un criterio fallido registra un código de motivo, como `acceptance_frame_rate_drop` o `hands_not_visible`. Después, un revisor confirma o anula el veredicto. Los códigos de motivo se enumeran en [Hora aceptada](/docs/es/fleet-learning/accepted-hour.md). Lea la aceptación con las herramientas MCP `get_result_acceptance` para una captura y `get_campaign_acceptance_summary` para una campaña. `list_capture_submissions` incluye el resumen de aceptación automática de cada captura. **Objetivos de calidad.** Un proyecto puede fijar umbrales sobre métricas de calidad, como la tasa de aceptación, la tasa de rechazo y la tasa de incidencias. Avala alerta cuando una métrica cruza su umbral. Léalos con la herramienta MCP `list_quality_targets`. Las verificaciones del programa que no son criterios automáticos, como la calibración, el consentimiento y la sincronización de marcas de tiempo, se informan como motivos de rechazo en el [informe de cobertura](/docs/es/fleet-learning/coverage.md). Consulte [Hora aceptada](/docs/es/fleet-learning/accepted-hour.md). ## Leer y escribir etiquetas de resultado Los endpoints REST están bajo `https://api.avala.ai/api/v1`: | Método y ruta | Qué hace | | - | - | | `GET /datasets/{owner}/{slug}/sequences/{sequence_uid}/outcome/` | Etiqueta vigente de una secuencia. `404` si no tiene etiqueta. | | `PUT /datasets/{owner}/{slug}/sequences/{sequence_uid}/outcome/` | Registra una nueva etiqueta vigente. | | `GET /datasets/{owner}/{slug}/sequences/{sequence_uid}/outcome/history/` | Todas las versiones de la etiqueta, de la más reciente a la más antigua. | | `GET /datasets/{owner}/{slug}/sequence-outcomes/` | Etiquetas vigentes de un dataset, paginadas. | La lista del dataset acepta los filtros `outcome`, `evaluation_membership`, `source` y `autonomy_level`. Cada uno admite un valor o una lista separada por comas, y una secuencia coincide con cualquier valor de la lista. `model_version` coincide con una versión exacta. Un valor de filtro desconocido devuelve `400`. La lista de secuencias, `GET /datasets/{owner}/{slug}/sequences/`, acepta `outcome` y `evaluation_membership` de la misma forma. Devuelve las secuencias cuya etiqueta vigente coincide. ### Escribir una etiqueta ```bash cURL theme={null} curl -X PUT \ "https://api.avala.ai/api/v1/datasets/your-org/kitchen-rollouts/sequences//outcome/" \ -H "X-Avala-Api-Key: $AVALA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "outcome": "failure", "progress": 0.4, "subtasks": [ { "label": "Place the plate in the lower rack", "start_ts": 0.0, "end_ts": 21.5, "outcome": "failure" } ], "mistake_type": "slip_during_place", "failure_stage": "place", "autonomy_level": "autonomous", "model_version": "your-policy@2026-09-20", "evaluation_membership": "held_out_eval", "source": "imported", "source_metadata": { "importer": "your-eval-harness", "run_id": "r42", "task": "load_dishwasher" } }' ``` ```python Python theme={null} from avala import Client client = Client() # reads AVALA_API_KEY label = client.sequence_outcomes.set( "your-org", "kitchen-rollouts", "", outcome="failure", progress=0.4, subtasks=[ {"label": "Place the plate in the lower rack", "start_ts": 0.0, "end_ts": 21.5, "outcome": "failure"}, ], mistake_type="slip_during_place", failure_stage="place", autonomy_level="autonomous", model_version="your-policy@2026-09-20", evaluation_membership="held_out_eval", source="imported", source_metadata={"importer": "your-eval-harness", "run_id": "r42", "task": "load_dishwasher"}, ) print(label.version, label.outcome) ``` ```typescript TypeScript theme={null} import Avala from "@avala-ai/sdk"; const avala = new Avala(); // reads AVALA_API_KEY const label = await avala.sequenceOutcomes.set("your-org", "kitchen-rollouts", "", { outcome: "failure", progress: 0.4, subtasks: [{ label: "Place the plate in the lower rack", startTs: 0.0, endTs: 21.5, outcome: "failure" }], mistakeType: "slip_during_place", failureStage: "place", autonomyLevel: "autonomous", modelVersion: "your-policy@2026-09-20", evaluationMembership: "held_out_eval", source: "imported", sourceMetadata: { importer: "your-eval-harness", run_id: "r42", task: "load_dishwasher" }, }); console.log(label.version, label.outcome); ``` ```bash CLI theme={null} avala sequence-outcomes set your-org kitchen-rollouts \ --outcome failure \ --progress 0.4 \ --subtasks-file subtasks.json \ --mistake-type slip_during_place \ --failure-stage place \ --autonomy-level autonomous \ --model-version your-policy@2026-09-20 \ --evaluation-membership held_out_eval \ --source imported \ --source-metadata '{"importer": "your-eval-harness", "run_id": "r42", "task": "load_dishwasher"}' ``` El SDK de TypeScript recibe nombres de opciones en camelCase y envía los campos de la API en snake\_case. Las claves dentro de `sourceMetadata` se envían tal como están escritas. En la CLI, `--hand-actions-file` recibe un archivo JSON con `{"left": [...], "right": [...]}`, y `--leakage-group KEY=ID` puede repetirse. ### Leer etiquetas ```bash cURL theme={null} # Current label of one sequence curl "https://api.avala.ai/api/v1/datasets/your-org/kitchen-rollouts/sequences//outcome/" \ -H "X-Avala-Api-Key: $AVALA_API_KEY" # Every version, newest first curl "https://api.avala.ai/api/v1/datasets/your-org/kitchen-rollouts/sequences//outcome/history/" \ -H "X-Avala-Api-Key: $AVALA_API_KEY" # Failed or aborted held-out sequences curl "https://api.avala.ai/api/v1/datasets/your-org/kitchen-rollouts/sequence-outcomes/?outcome=failure,aborted&evaluation_membership=held_out_eval" \ -H "X-Avala-Api-Key: $AVALA_API_KEY" # The sequences themselves, filtered by their current label curl "https://api.avala.ai/api/v1/datasets/your-org/kitchen-rollouts/sequences/?outcome=mistake_and_recovery,intervention" \ -H "X-Avala-Api-Key: $AVALA_API_KEY" ``` ```python Python theme={null} from avala import Client client = Client() label = client.sequence_outcomes.get("your-org", "kitchen-rollouts", "") versions = client.sequence_outcomes.history("your-org", "kitchen-rollouts", "") page = client.sequence_outcomes.list( "your-org", "kitchen-rollouts", outcome=["failure", "aborted"], evaluation_membership="held_out_eval", model_version="your-policy@2026-09-20", ) for item in page: print(item.sequence_uid, item.outcome, item.progress) ``` ```typescript TypeScript theme={null} import Avala from "@avala-ai/sdk"; const avala = new Avala(); const label = await avala.sequenceOutcomes.get("your-org", "kitchen-rollouts", ""); const versions = await avala.sequenceOutcomes.history("your-org", "kitchen-rollouts", ""); const page = await avala.sequenceOutcomes.list("your-org", "kitchen-rollouts", { outcome: ["failure", "aborted"], evaluationMembership: "held_out_eval", modelVersion: "your-policy@2026-09-20", }); for (const item of page.items) { console.log(item.sequenceUid, item.outcome, item.progress); } ``` ```bash CLI theme={null} avala sequence-outcomes get your-org kitchen-rollouts avala sequence-outcomes history your-org kitchen-rollouts avala sequence-outcomes list your-org kitchen-rollouts \ --outcome failure,aborted \ --evaluation-membership held_out_eval ``` La lista del dataset devuelve hasta 100 etiquetas por página. Pase el `cursor` de la página anterior para continuar. ### Leer etiquetas con el servidor MCP El servidor MCP lee etiquetas de resultado. No las escribe. * `get_sequence_outcome` recibe `owner`, `slug` y `sequenceUid`. Devuelve la etiqueta vigente. * `list_sequence_outcomes` recibe `owner` y `slug`, más los filtros `outcome`, `evaluationMembership`, `source`, `autonomyLevel` y `modelVersion`, y `limit` y `cursor`. Ambas herramientas devuelven una forma breve por defecto. Pase `detail: "full"` para incluir subtareas, acciones de las manos, las etiquetas de error y de recuperación, los grupos de fuga, los metadatos de origen y quién etiquetó. Consulte [Use Avala con IA](/docs/es/getting-started/mcp.md) para conectarse. ## Exportar etiquetas de resultado con LeRobot El exportador de LeRobot puede escribir la etiqueta de resultado vigente de cada secuencia junto al dataset. Una secuencia de Avala se convierte en un episodio de LeRobot. ```bash CLI theme={null} avala lerobot export your-org/kitchen-rollouts \ --repo-id your-hf-user/kitchen-rollouts \ --output ./lerobot-out \ --include-outcomes ``` ```python Python theme={null} from avala import Client from avala.lerobot import export_dataset export_dataset( Client(), "your-org", "kitchen-rollouts", repo_id="your-hf-user/kitchen-rollouts", output_dir="./lerobot-out", include_outcomes=True, ) ``` Las etiquetas se escriben en `meta/avala_sequence_outcomes.jsonl`, un objeto JSON por línea y una línea por cada episodio de LeRobot guardado. La tabla de episodios propia de LeRobot no tiene lugar para estos metadatos, así que van en un archivo aparte. Cada línea tiene estas claves: | Clave | Valor | | - | - | | `episode_index` | El índice del episodio de LeRobot. | | `avala_sequence_uid` | La secuencia de Avala de la que proviene el episodio. | | `outcome` | El valor de resultado, o `null` cuando la secuencia no tiene etiqueta. | | `outcome_version` | La versión de la etiqueta que se exportó. | | `progress`, `quality`, `speed` | Como en la etiqueta. | | `subtasks`, `hand_actions` | Como en la etiqueta. Las marcas de tiempo son segundos desde el inicio del episodio. | | `mistake_type`, `recovery_type`, `failure_stage`, `autonomy_level`, `model_version`, `evaluation_membership` | Como en la etiqueta, con `null` en lugar de un valor vacío. | | `leakage_groups` | Como en la etiqueta. | | `outcome_source`, `outcome_source_metadata`, `outcome_confidence` | Los campos `source`, `source_metadata` y `confidence` de la etiqueta. | Una secuencia sin etiqueta recibe una línea con solo `episode_index`, `avala_sequence_uid` y `"outcome": null`. ## El carril de fallo y recuperación Los fallos recuperables se entregan como su propio carril: las secuencias cuyo resultado es `mistake_and_recovery` o `intervention`. Las subtareas y las acciones de las manos de cada secuencia marcan dónde ocurren el fallo y la recuperación. El carril se entrega como un slice aparte dentro de la release. Usted puede entrenar con él, ponderarlo o dejarlo fuera. También puede construir el mismo conjunto usted mismo con `?outcome=mistake_and_recovery,intervention`. Las secuencias inseguras no forman parte del carril.