Pipeline semantiche

Le pipeline semantiche descrivono come i dati conformi a un contratto passano attraverso Guida. Collegano un’origine o un estrattore a controlli di convalida, trasformazioni e destinazioni, rendendo il lavoro proposto verificabile prima dell’esecuzione.

Una pipeline non è una cartella di flusso di lavoro, un pool di processi di lavoro o un pianificatore automatico. I flussi attivano un contesto operativo, i processi consumano le code e il registro di tracciabilità conserva i dati persistenti sulle esecuzioni e sui singoli elementi. La pipeline collega questi ambiti mediante una provenienza esplicita.

Struttura a fasi

Fase	Responsabilità
Source	Dichiara il tipo o lo schema in ingresso
Extractor	Esegue un estrattore identificato e vincolato da contratto
Validator	Applica uno schema e regole circoscritte sui singoli elementi
Mapper	Trasforma un contratto dichiarato in un altro
Destination	Indica la coda o un’altra destinazione supportata

Controlli di convalida, mapper e destinazioni formano cataloghi riutilizzabili. In questo modo le decisioni sulla struttura dei dati e sulle regole operative non rimangono nascoste in script occasionali.

{
  "id": "careers.example.discovery-to-fetch",
  "workflowName": "careers-crawl",
  "status": "draft",
  "stages": [
    {
      "id": "discover",
      "kind": "extractor",
      "extractorId": "careers.example.jobs"
    },
    {
      "id": "validate",
      "kind": "validator",
      "schema": "schemas/career-job-output.schema.json",
      "validation": {
        "itemRules": {
          "requiredFields": ["url"],
          "urlFields": ["url"],
          "dedupeKey": "url"
        }
      }
    },
    {
      "id": "map",
      "kind": "mapper",
      "mapperId": "careers.example.jobs.fetchPayload"
    },
    {
      "id": "enqueue",
      "kind": "queue",
      "destinationId": "careers.fetch.queue"
    }
  ]
}

Definizioni dirette, modelli e generazione

Una pipeline può essere scritta direttamente oppure derivata da un modello riutilizzabile. Una regola di generazione seleziona i descrittori e collega i valori del modello in modo esplicito:

{
  "template": "careers.discovery-to-fetch",
  "selector": {
    "domain": "careers",
    "source": { "kind": "web" },
    "certifiable": true
  },
  "idPattern": "${extractor.id}.discovery-to-fetch",
  "bindings": {
    "extractorId": "$extractor.id",
    "companyName": "$extractor.input.defaultCompanyName",
    "sourcePortalUrl": "$extractor.source.url"
  }
}

Le associazioni sono dati dichiarati, non supposizioni. Guida non ricava azienda, destinazione o contratto da un ID, dal percorso o dal nome di un file.

Percorso sicuro verso l’esecuzione

1. Draft e diff risolvono la definizione effettiva e mostrano le modifiche proposte ai file.
2. Validate controlla struttura, riferimenti, contratti e grafo.
3. Preflight verifica lo spazio di lavoro e i prerequisiti operativi correnti.
4. Plan espone fasi, collegamenti, modifiche previste, capacità richieste, regole, credenziali, provenienza, possibilità di ripristino, blocchi e avvisi.
5. Preview restituisce un hash della proposta esatta e indica se può essere eseguita.
6. Start accetta input e limiti di coda espliciti. Le operazioni più impegnative conservano i controlli di conferma e autorizzazione.

Il salvataggio o l’eliminazione modifica i file dello spazio di lavoro e non è mai una conseguenza implicita dell’apertura dell’editor. Anche l’avvio resta separato dalla modifica della definizione.

Esecuzione, provenienza e ripristino

Ogni esecuzione crea un legame esplicito con una voce del flusso di lavoro. La destinazione della coda dichiara se creare un’esecuzione isolata o usarne una esistente. Guida registra lo stato delle fasi, le dipendenze, i riferimenti agli output, le decisioni di deduplicazione e gli esiti operativi.

workspace.pipelines.execution.lifecycle.get restituisce gli stati dell’esecuzione e delle fasi gestite dalla pipeline. L’anteprima del lavoro a valle mostra code e modifiche previste; avvio e controllo sono richieste separate. Gli esiti vengono riconciliati esplicitamente con code e registro: una coda vuota, da sola, non dimostra che l’esecuzione sia riuscita.

La Remote Ops API espone contratti per lettura, bozza, confronto, convalida, controlli preliminari, piano, anteprima, avvio, risultati, prove, lavoro a valle e controllo. Guida Control usa questi contratti e non avvia una pipeline soltanto perché un operatore ha salvato una bozza.