Gestão de Contextos
===================

Camada de governança responsável pelo catálogo global de identificadores e pela integridade referencial entre as camadas de Banco de Dados (Menthor DB) e Arquivos (Menthor Files).

Fluxo de Operação e Diagnóstico
-------------------------------

O sistema utiliza agregação paralela para fornecer uma visão consolidada de todas as fontes de dados vinculadas a um ID de contexto.

1. **Consulta Unificada**: Chamada de ``/context/{id_context}``. Dispara buscas simultâneas em metadados estruturados (tabelas) e vetoriais (documentos).
2. **Resposta Híbrida**: Retorno de um objeto consolidado contendo os nós ``db_data`` e ``files_data``.
3. **Sinalização de Integridade**: Caso os metadados de busca vetorial estejam parciais ou inconsistentes, o sistema utiliza o status **207 Multi-Status**.

.. warning::
   **Tratamento do Status 207 (Multi-Status)**: Indica que o contexto foi localizado, mas o motor vetorial (Files) possui falhas ou está pendente. O acesso aos dados de Banco de Dados (DB) permanece funcional, mas a busca em documentos pode estar degradada.

Modelos de Operação
-------------------

* **Catálogo Global (list_all_contexts)**: 
  Endpoint: ``/context/all``
  Recupera a lista de todos os contextos registrados no ecossistema Menthor, servindo como o dicionário mestre de IDs e de descrições dos dados.

* **Consulta Detalhada (get_context_information)**: 
  Endpoint: ``/context/{id_context}``
  Realiza uma busca exaustiva por metadados associados a um ID. Agrega informações de tabelas (DB) e documentos (Files) em uma única resposta estruturada.

* **Expurgo Inteligente (delete_context)**: 
  Endpoint: ``/context/delete_context/{id_context}``
  Executa a limpeza física profunda e segura do contexto, gerenciando referências cruzadas:

  * **Deleção de DB**: Remove permanentemente o arquivo de metadados de banco de dados (recurso privado do contexto).
  * **Reference Counting (Files)**: O arquivo físico de uma Vector Store só é deletado se o contexto atual for o proprietário exclusivo. Se houver compartilhamento, apenas o vínculo é removido.
  * **Limpeza de Registro**: O ID do contexto é removido do catálogo global (``id_context_list.json``) via *File Lock*.

.. note::
  **Idempotência de Deleção**: Todas as operações de remoção retornam sucesso informativo mesmo se o registro já não existir (ou já tiver sido removido), garantindo resiliência em fluxos de automação e limpeza.

Referência Técnica da API
-------------------------

**Exclusão em Provedores Externos**: Os endpoints de deleção aqui descritos gerenciam principalmente o **armazenamento local** de metadados. 
Para evitar faturamentos desnecessários e garantir a conformidade de dados, a exclusão permanente dos recursos na OpenAI deve ser realizada previamente.

Abaixo estão detalhados os endpoints para gestão avançada de arquivos e Vector Stores.

.. toctree::
  :maxdepth: 1
  :titlesonly:

  ../openai_api