Pipelines declarativos

tecsas3 pipe ejecuta workflows declarativos definidos en YAML o JSON. Cada step es una llamada real al CLI (tecsas3 <recurso> <comando> --flag valor); el orquestador (cli/src/tecsas3_cli/resources/pipeline.py) se encarga de resolver placeholders, propagar resultados entre steps y reportar el resultado final en JSON determinista. Es la pieza que hace el CLI componible: un agente puede describir un workflow complejo y el CLI lo ejecuta paso a paso sin necesidad de escribir bash.

Anatomía de un pipeline

steps:
  - id: <identificador único>          # usado en placeholders ${id.path}
    resource: <recurso>                 # paciente, ia, hce, fhir, examen, ...
    command: <acción>                   # list, get, create, ai-query, ...
    args:                                # mapa de flags (--clave valor) o _positional
      _positional: <valor o ${expr}>
      flag-uno: valor
      flag-dos: true                    # boolean → se serializa como --flag-dos
    env:                                # opcional, variables de entorno del step
      KEY: value
    continue_on_error: false            # default false; true → no aborta el pipeline

Campos obligatorios (validados por _validate_steps() en pipeline.py:109-123): id, resource, command. El id no puede contener espacios y debe ser único dentro del pipeline — se usa como clave de contexto para los placeholders.

Placeholders

La resolución ocurre en _resolve() (pipeline.py:46-65) antes de cada invocación. Hay tres formas de expresar una referencia:

Sintaxis	Significado
`${step_id.path.to.value}`	Valor producido por un step anterior (dotted/bracket).
`${env.VAR_NAME}`	Variable de entorno leída en el momento de la ejecución.
`_positional: <valor o ${expr}>`	Valor posicional (no lleva `--clave`).

Los placeholders se interpolan dentro de strings (sustitución parcial) y también se evalúan cuando toda la cadena es un placeholder puro (preservando el tipo original: número, lista, dict).

- id: buscar
  resource: ia
  command: v2-patient-search
  args:
    q: juan

- id: crear_chat
  resource: ia
  command: v2-chat-create
  args:
    tipo: triage
    titulo: Chat desde pipeline
    paciente-uuid: ${buscar.results[0].id_paciente}   # accesor anidado + índice

- id: preguntar
  resource: ia
  command: v2-chat-mensaje
  args:
    _positional: ${crear_chat.id}                     # placeholder puro → tipo preservado
    pregunta: "¿Cómo te sientes hoy?"

Los accesores anidados usan dot path o bracket index y se resuelven en _dotted_get() (pipeline.py:27-43). El patrón más habitual es ${step.results[i].campo} para iterar la primera/ensima posición de un array de resultados: por ejemplo ${buscar.results[0].id_paciente} extrae el UUID del primer paciente devuelto por ia v2-patient-search.

Ejemplo: workflow de tres steps

# 1) Buscar pacientes por texto
- id: buscar
  resource: ia
  command: v2-patient-search
  args:
    q: juan
    limit: 5

# 2) Crear historia clínica (HCE) en borrador para el primer resultado
- id: crear_hce
  resource: hce
  command: historia-create
  args:
    paciente-uuid: ${buscar.results[0].id_paciente}
    tipo: CONSULTA
    estado: BORRADOR

# 3) Notificar al médico asignado
- id: notificar
  resource: ia
  command: consulta-libre
  continue_on_error: true   # la notificación falla, no abortamos el pipeline
  args:
    pregunta: "Tienes una nueva historia en borrador: ${crear_hce.id}"
    proveedor: gemini

Modos de ejecución

dry-run
output-all

Imprime la definición validada sin ejecutar nada. Útil para revisar el plan antes de invocar APIs reales.

tecsas3 pipe run --dry-run workflow.yml

Salida (JSON, recortada):

{
  "steps": [
    {"id": "buscar", "resource": "ia", "command": "v2-patient-search", "args": {"q": "juan", "limit": 5}},
    {"id": "crear_hce", "resource": "hce", "command": "historia-create", "args": {"paciente-uuid": "${buscar.results[0].id_paciente}", "tipo": "CONSULTA", "estado": "BORRADOR"}},
    {"id": "notificar", "resource": "ia", "command": "consulta-libre", "args": {"pregunta": "Tienes una nueva historia en borrador: ${crear_hce.id}", "proveedor": "gemini"}, "continue_on_error": true}
  ]
}

Devuelve todos los outputs de los steps ejecutados, no solo el último. Esencial para debug, auditoría y para alimentar pipelines downstream.

tecsas3 pipe run workflow.yml --output-all

Salida (JSON, recortada):

[
  {"id": "buscar", "status": "success", "exit_code": 0, "result": {"results": [{"id_paciente": "abc-123", "nombre": "Juan Pérez"}]}},
  {"id": "crear_hce", "status": "success", "exit_code": 0, "result": {"id": "hce-789", "estado": "BORRADOR"}},
  {"id": "notificar", "status": "success", "exit_code": 0, "result": {"respuesta": "Notificación enviada"}}
]

Sin --output-all la salida se reduce al último step, idéntica a una llamada pipe run normal.

Comandos disponibles

Comando	Función
`tecsas3 pipe run FILE`	Ejecuta el pipeline. Soporta `--dry-run`, `--output-all`, `--verbose`.
`tecsas3 pipe validate FILE`	Valida la sintaxis sin ejecutar nada; retorna `{valid, steps, ids[]}`.
`tecsas3 pipe init [NAME]`	Genera un pipeline de ejemplo (`pipeline.yml` por defecto). Soporta `--force`.

Cada step se ejecuta dentro de un CliRunner de Typer con el mismo Runtime (rt: Runtime = ctx.obj) que la invocación principal. Esto significa que el token, el tenant configurado y el formato de salida se heredan del proceso padre. Si lanzas tecsas3 --json --no-input pipe run workflow.yml, todos los steps se ejecutan también en modo JSON.

Manejo de errores

Default (continue_on_error: false) — el primer step que devuelve exit_code != 0 aborta el pipeline. El orquestador emite {error, step, outputs} con exit_code no-cero.
continue_on_error: true — el step que falla se registra con status: "error" y stderr capturado, y el pipeline continúa. Los placeholders que dependan de ese step reventarán en _resolve() (KeyError); protégelos también con continue_on_error en el step que los consume.
Placeholder no resuelto — el error aparece antes de invocar el sub-comando, así que el step queda registrado como skipped (no llama a la API).

Validación previa

tecsas3 pipe validate no hace red: solo parsea el YAML/JSON y comprueba que steps contenga una lista de dicts con los campos obligatorios. Es seguro en CI:

tecsas3 pipe validate workflow.yml
# → {"valid": true, "steps": 3, "ids": ["buscar", "crear_hce", "notificar"]}

Referencias

cli/src/tecsas3_cli/resources/pipeline.py:46-65 — _resolve() (placeholders en strings)
cli/src/tecsas3_cli/resources/pipeline.py:27-43 — _dotted_get() (dot/bracket paths)
cli/src/tecsas3_cli/resources/pipeline.py:84-106 — _args_to_argv() (mapa → flags CLI)
cli/src/tecsas3_cli/resources/pipeline.py:109-123 — _validate_steps() (campos mínimos)
cli/data/pipeline_examples/ — ejemplos: triage.yml, export_fhir.yml, icd_workflow.yml

Empezar

Conceptos

Guías

Soporte

Pipelines declarativos

Anatomía de un pipeline

Placeholders

Ejemplo: workflow de tres steps

Modos de ejecución

Comandos disponibles

Manejo de errores

Validación previa

Referencias

​Anatomía de un pipeline

​Placeholders

​Ejemplo: workflow de tres steps

​Modos de ejecución

​Comandos disponibles

​Manejo de errores

​Validación previa

​Referencias

Anatomía de un pipeline

Placeholders

Ejemplo: workflow de tres steps

Modos de ejecución

Comandos disponibles

Manejo de errores

Validación previa

Referencias