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

Focado na gestão de bases de conhecimento vetoriais (Vector Stores) via OpenAI, permitindo a busca semântica em documentos PDF, XLSX e TXT, entre outros formatos.

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

O processamento de arquivos é **assíncrono** devido à latência de download e indexação dos provedores de IA.

1. **Início**: Chamada de ``/storage/upload_files`` (Criação) ou ``/storage/update_files`` (Atualização).
2. **Resposta Imediata**: Validação de cotas, download local dos arquivos e retorno **202 Accepted**.
3. **Indexação (Background)**: Upload para o storage da OpenAI, criação/atualização da Vector Store e processamento de *Batches*.
4. **Notificação (Webhook)**: Envio de relatório consolidado (Sucesso, Parcial ou Erro) para a plataforma externa:
   
   .. code-block:: none

      /company-contexts/partners/context/{id_context}/processed

.. important::
   **Limite de Cota**: Cada contexto é limitado estritamente a **2 Vector Stores** ativas simultaneamente. Para adicionar uma nova, uma existente deve ser removida ou desassociada.

Estados de Processamento (Callback)
-----------------------------------

* **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 Operação
-------------------

* **Criação e Indexação Total (upload_files)**: 
  Endpoint: ``/storage/upload_files``
  Inicializa uma base de conhecimento do zero. Se o download de todos os arquivos falhar, a operação é abortada antes do agendamento.
* **Sincronização Evolutiva (update_files)**: 
  Endpoint: ``/storage/update_files``
  Realiza o *Upsert* (atualização incremental). Arquivos omitidos no novo payload são removidos automaticamente da OpenAI e do storage local.
* **Gestão de Vínculos (associate_vs_to_context/remove_vs_from_context)**: 
  Endpoints: ``/storage/associate_vs_to_context`` e ``/storage/remove_vs_from_context``
  Permite associar ou desvincular IDs de Vector Stores existentes a um contexto sem deletar os dados na OpenAI. Útil para reaproveitamento de bases entre contextos.
* **Exclusão de Metadados (delete_vs_metadata)**:
  Endpoint: ``/storage/delete_vs_metadata``
  Limpeza global de referências a uma Store específica em todo o sistema local, liberando cotas de todos os contextos afetados. Não altera armazenamento em OpenAI.