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.

Aviso

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.

Nota

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.