Utilizzo

Gestione dei file ricevuti

I file provenienti dalla chat sono accessibili dentro context tramite:

• memory_agent.message_memory.history -> List[ChatMessage] contiene la lista di messaggi ricevuti ed inviati all'utente;
• input.attachments -> List[FileMetadata] restituisce i file eventualmente allegati nell'ultimo messaggio inviato dall'utente.

Relativamente ai file contenuti nei chunk, ogni volta che si esegue un nodo di tipo query, dentro l'argomento special.assets della sua callback after è presente la lista di tutti gli asset (List[FileMetadata]) appartenenti ai chunk estratti

FileMetadata è la classe che contiene delle informazioni base per far riferimento al file. Essa è così definita:

class FileMetadata:
    name: str   # nome del file su s3
    original_name: str | None # nome originale del file
    format: Literal['pdf', 'docx', 'excel', 'jpg', 'jpeg', 'png']   # formato del file
    chunk_id: int | None  # l'id del chunk di provenienza del file
    node_id: int | None  # l'id del nodo di provenienza del chunk

informazioni

Il chunk_id ed il node_id sono definiti solo quando i file provengono dal Vector Store.

Gestione file generati

Nel caso di un file generato tramite script o comunque proveniente da sorgenti diverse dalla chat e dal vector store, per inviarlo all'utente o ad un LLM occorre prima produrre il FileMetadata associato tramite la funzione asincrona upload.

await context.file_agent.upload(name: str, content: bytes) -> FileMetadata

informazioni

Il nome del file deve comprendere il formato (es: file.png). I formati supportati sono: 'txt', 'pdf', 'docx', 'excel', 'png', 'jpeg', 'jpg'

Analisi dei file tramite LLM

Per inviare uno o più file ad un LLM occorre fare ricorso ad un nodo di tipo llm e passare i file tramite gli argomenti files o segments callback prompt insieme alle istruzioni testuali.

Invio dei file in risposta

L'invio dei file all'utente avviene tramite la callback emit del nodo emit. In particolare esistono 2 modalità distinte:

• manuale: tramite la proprietà attachments nell'output della callback. In questo caso, tutti i file specificati saranno sempre visibili nel messaggio di risposta;
• intelligente: tramite la proprietà dynamic_attachments nell'output della callback. In questo caso, i file saranno effettivamente mostrati all'utente se all'interno della risposta sono espressamente citati. Un file è conisederato citato se il suo nome appare all'interno della risposta all'interno di due parentesi graffe: {{file_name.pdf}}. Il frontend provvederà a nascondere la stringa tra parentesi e mostrare l'asset associato.

warning

Se all'interno dello stesso messaggio vengono inviati più file con lo stesso nome, in caso in cui questi vengano citati, ne sarà mostrato solamente uno!

warning

Al momento, l'invio dei file in chat è disponibile solo con la skill Web Chat. Whatsapp non è supportato!

Funzionalità avanzate

Quando occorre processare i file in modo più avanzato è possibile ricorrere al metodo asincrono:

context.file_agent.get(file: FileMetadata) -> PdfAgent | WordAgent | ExcelAgent | ImageAgent

Tale funzione restituisce degli oggetti specifici in base alla tipologia di file che offrono alcune funzioni utili.