Chunk

I chunk sono le unità di informazione che possono essere aggiunte dentro i nodi del grafo.

Questi svolgono due ruoli distinti durante l'esecuzione dell'albero:

1. durante la fase 3 dello step explore, tutti i chunk possono contribuire per definire il percorso nel grafo da seguire per trovare il prossimo nodo da eseguire.
2. durante lo step execute di un nodo di tipo query, solo i chunk con proprietà for_rag = True possono essere recuperati a seguito di una query definita con l'apposita callback.

informazioni

Un nodo che non contiene alcun chunk e che non ha nodi figli non sarà mai considerato dal sistema di ricerca durante lo step explore, potrà essere eseguito solo se esplicitamente richiamato da una callback before_run o after di un altro nodo.

Inserimento

I chunk possono essere aggiunti in tre modalità distinte:

1. manualmente tramite interfaccia grafica;
2. importando un json;
3. utilizzando l'apposita interfaccia API.

In generale, quando si aggiunge un chunk occorre definire le seguenti proprietà:

• name (str) un nome che funge da titolo;
• content (str) il contenuto testuale del chunk;
• for_rag (bool) se False significa che il chunk sarà usato solo per la ricerca nello step di explore, ma NON per il RAG. Altrimenti se True sarà impiegato per entrambi gli scopi;
• extra (dict) sono delle proprietà personalizzabili aggiuntive che possono essere associate a ciascun chunk con properità for_rag = True. Oltre a poter essere recuperate in fase di estrazione, possono essere usate per filtrare i chunk prima di usare l'embedding;
• assets (list) possono essere associati a ciascun chunk con properità for_rag = True. Sono una lista di file (immagini, documenti pdf) associati al chunk. Tali file, come descritto nella sezione dedicata al File Agent, possono essere utilizzati in vari modi.

Tramite interfaccia grafica, oltre a poter aggiungere i chunk, uno alla volta, compilando i relativi campi in una form, è possibile importarli a gruppi tramite un file json con la seguente struttura:

[
  {
    "name": "(str): Nome del chunk",
    "content": "(str): Contenuto del chunk (obbligatorio)",
    "forRag": "(bool): Se il chunk deve essere utilizzato per RAG o meno",
    "extra": "(dict): Extra del chunk con formato json",
    "metadata": "(dict): Metadata facoltativi del chunk con formato json",
    "assets": "(List[str]): Array di stringhe contenete i nomi dei file",
    "assetsToAdd": [
      {
        "name": "(str): Nome del file che corrisponde a quello in 'assets'",
        "base64content": "(str): Base64 del file"
      }
    ]
  }
]

Infine, nel caso in cui sia necessario importare grandi quantità di chunk, oppure si voglia rendere il contentuto del Vector Store controllabile dall'esterno, il Tree Agent offre un interfaccia API che permette di inserire e rimuovere i chunk contenuti nei singoli nodi.

warning

Gli extra associati ad un chunk devono essere organizzati dentro un dizionario ad un singolo livello. Pertanto non sono ammessi dizionari annidati!

Endpoint API Chunks

Gli endpoint disponibili sulla piattaforma CAITY (esposti attraverso l'API CAITY Skill) permettono di gestire i chunk associati ai nodi di un Tree Agent tramite API REST. Tramite il suo utilizzo è possibile creare, aggiornare o eliminare i chunk di un determinato nodo.

Tutti gli endpoint richiedono come parametri di percorso:

• setupId – l’identificativo univoco del setup (UUID)
• nodeId – l’identificativo numerico del nodo (integer)

Per interfacciarsi con l'API, è necessario creare una API key associata al setup tramite l'utilizzo della piattaforma CAITY Lab. Dopo aver ottenuto la chiave, è necessario includerla all'interno dell'header X-Api-Key nella richiesta da effettuare.

Creazione di nuovi chunk

POST https://<caity_skill_url>/api/v1/{setupId}/tree-agent/nodes/{nodeId}/chunks

Crea uno o più nuovi chunk all’interno di un nodo specifico.

Il body di seguito segue in larga parte la struttura del JSON sopra descritto:

[
  {
    "nodeId": 0,
    "name": "string",
    "content": "string",
    "forRag": true,
    "assets": ["string"],
    "extra": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "assetsToAdd": [
      {
        "name": "string",
        "base64Content": "string"
      }
    ]
  }
]

In caso di successo (HTTP 200), la riposta segue il seguente formato:

{
  "trackingId": "string"
}

dove trackingId rappresenta l'id per tracciare l'esecuzione del job, consultabile tramite la rotta GET https://<caity_skill_url>/api/v1/tracking/{trackingId}.

Aggiornamento di chunk esistenti

PUT https://<caity_skill_url>/api/v1/{setupId}/tree-agent/nodes/{nodeId}/chunks

Aggiorna uno o più chunk già esistenti nel nodo indicato.

Il body segue il seguente formato:

[
  {
    "nodeId": 0,
    "name": "string",
    "content": "string",
    "forRag": true,
    "assets": ["string"],
    "extra": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "assetsToAdd": [
      {
        "name": "string",
        "base64Content": "string"
      }
    ],
    "chunkId": 0,
    "assetsToRemove": ["string"]
  }
]

In particolare, con il campo chunkId è possibile indicare l'id del chunk da modificare.

In caso di successo (HTTP 200), la riposta segue il seguente formato:

{
  "trackingId": "string"
}

dove trackingId rappresenta l'id per tracciare l'esecuzione del job, consultabile tramite la rotta GET https://<caity_skill_url>/api/v1/tracking/{trackingId}.

Eliminazione di chunk

POST https://<caity_skill_url>/api/v1/{setupId}/tree-agent/nodes/{nodeId}/chunks:bulk-delete

Elimina in blocco uno o più chunk associati a un nodo specifico.

In questo caso il body contiene tutti gli id dei chunk da eliminare:

[ 1, 2, 5, 8 ]

In caso di successo, viene restituito una risposta di tipo HTTP No Content (204), senza un payload di output.

Utilizzo

A seguito dell'esecuzione di un nodo query, i chunk individuati vengono restituiti dentro l'argomento special.chunks come una lista di istanze della classe Chunk come di seguito definita:

class Chunk:
    id: int   # l'id del chunk
    content: str  # il contenuto testuale
    node_id: int   # l'id del nodo che contiene il chunk
    extra: Dict[str, str | int | float | bool]  # aventuali proprietà extra associate al chunk

informazioni

Gli asset sono resi disponibili dentro l'argomento special.assets