Menthor Files: Documentos e Vetores
===================================

Focado na gestão de bases de conhecimento vetoriais (Vector Stores) via OpenAI.

Fluxo de Operação
-----------------

1. **Início**: Chamada de ``/files/upload_files`` (POST) ou ``/files/update_files`` (PATCH).
2. **Resposta Imediata**: Download local e retorno **202 Accepted**.
3. **Indexação (Background)**: Upload para OpenAI e criação de *Batches*.
4. **Notificação (Webhook)**: Relatório consolidado de sucesso ou falha parcial.

Estados de Processamento
------------------------

* **SUCCESS**: Tudo indexado.
* **PARTIAL_SUCCESS**: Sucesso na criação da Store, mas com falha em arquivos específicos (detalhado no callback).
* **ERROR**: Falha crítica total.


Modelos de Ingestão: Criação vs. Sincronização
----------------------------------------------

* **Criação e Indexação Total (upload_files)**: 
  Utilizado para inicializar uma nova base de conhecimento do zero.
* **Sincronização Evolutiva (update_files)**: 
  Utilizado para manutenção e atualização incremental (*Upsert*) de uma base existente.

.. important::
   No **PATCH (update)**, arquivos omitidos no payload são removidos automaticamente do storage e do sistema.